getEndpointsList

This method returns the list of endpoints.

Important

This method has been updated to version 1.1. For information applicable to version 1.0, refer to this section.

Parameters

Parameter	Type	Optional	Description
`parentId`	String	Yes	The ID of the target company or group. If not specified, the method returns items that are in the targets of the company linked to the API key. Note To retrieve information on Active Directory endpoints, use the getNetworkInventoryItems method.
`isManaged`	Boolean	Yes	The flag to list managed or unmanaged endpoints. By default, the parameter is not set and the method returns all the managed and unmanaged endpoints. If set on `True`, the method returns only managed endpoints.
`page`	Number	Yes	The results page number.. Default value: `1`.
`perPage`	Number	Yes	Number of items per page to be returned. Possible values: `1` - `1000`. Default value: 30.
`filters`	Object	Yes	The parameters used to customize the type of endpoints you want to retrieve. For information regarding the available filters and how to use them, refer to Available Filters.
`options`	Array	Yes	A set of options that control what information is present in the response.

Available Filters

You can use the filters parameter to query the endpoints by certain properties. Filters are structured in sections and subsections, described hereinafter

The query result is a list of endpoints that match ANY selected filter in ALL sections AND subsections.

These are the available filtering options:

Section	Subsection	Filtering Options
`security`	management	`managedWithBest` - a Boolean to filter all endpoints with the security agent installed on them. Default value: `False`. `managedExchangeServers` - a Boolean to filter all protected Exchange servers. Default value: `False`. This filter requires a valid license key that covers the security service. `managedRelays` - a Boolean to filter all endpoints with Relay role. Default value: `False`. `securityServers` - a Boolean to filter all Security Servers. Default value: `False`.
`depth`		`allItemsRecursively` - a Boolean to filter all endpoints recursively within the Network Inventory of a company. Default value: `False`.
`details`		`ssid` - string, the SSID (Active Directory SID of the endpoint) used to filter the endpoints regardless of their protection status. `macs` - array, the list of MAC addresses used to filter the endpoints regardless of their protection status. `name` - string, used for filtering the endpoints by name regardless of their protection status. Minimum required string length is three characters.

Important

Some filters require a specific license to be active, otherwise they are ignored, resulting in an inaccurate API response.

The field name works with partial matching.

The filter returns the endpoints whose names are exact match or start with the specified value. To use the specified value as a suffix, use the asterisk symbol (*).

For example:

If name is computer, the API returns all endpoints whose names start with computer.

If name is *puter, then the API returns a list of all endpoints that contain puter in their names.

Available options

You can use the options parameter to customize what information is included in the API response. Options are structured in sections and subsections, described hereinafter.

These are the available options:

Section	Description
`returnProductOutdated`	Boolean. If `true`, the `productOutdated` attribute is included in the API response.
`includeScanLogs`	Boolean. If true, the `lastSuccessfulScan` attribute is included in the API response. Default value: `false`.

Return value

This method returns an Object containing information about the endpoints. The returned object contains:

page - the number of the page that is currently displayed.
pagesCount - the total number of pages.
Note
This attribute is only displayed on page 1.
perPage - the total number of items displayed per page.
total - the total number of items returned by the request.
Note
This attribute is only displayed on page 1.
hasMoreRecords - Boolean, indicates if there are any more records on the next page.
items - an array containing the list of endpoints. Each entry in the list has the following fields:
- id, the ID of managed endpoint,
- name, the name of the endpoint,
- label, the label set to this endpoint,
- fqdn, the FQDN of the endpoint,
- groupId, the group ID of the endpoint,
- isManaged, boolean True, if this endpoint is managed,
- machineType, the type of the machine: (1 - computer, 2 - virtual machine, 3 - EC2 Instance, 0 - Other),
- operatingSystemVersion, the operating system version of the endpoint,
- ip, the IP address of the endpoint,
- macs, the MAC addresses of the endpoint,
- ssid, the SSID (Active Directory SID) of the endpoint,
- managedWithBest, boolean True, if BEST is installed on this endpoint,
- isContainerHost, boolean True, if this endpoint is a Container Host,
- managedExchangeServer, boolean True, if this endpoint is an Exchange Server,
- managedRelay, boolean True, if this endpoint has Relay role,
- securityServer, boolean True, if this endpoint is a Security Server,
- policy, an Object informing about the policy active on the endpoint. The object contains the following fields:
  - id - a String uniquely identifying the active policy,
  - name - the name of the policy,
  - applied - a Boolean set to True if the policy is currently applied on the endpoint,
movingInfo, an Object informing upon endpoint transfer from one company to another one. The object contains:
- state - the endpoint moving status (0 - in progress, 1 - moved),
- destinationCompanyName - the name of the company where the endpoint was moved.
productOutdated, boolean True, if the endpoint is missing one ore more agent updates.
lastSuccessfulScan, object. Includes the following details:
- name - the name of the scan.
- date - the date on which the scan was performed.

Example

Request:

{
      "params": {
           "parentId": "63c6bb02e3cb799758020b99",
           "page": 1,
           "perPage": 3,
           "filters": {
                   "security": {
                            "management": {
                                "managedWithBest": true,
                                "managedRelays": true
				}
                   }
		},
           "options": {
                   "returnProductOutdated": true,
                   "includeScanLogs": true
           }
      },
      "jsonrpc": "2.0",
      "method": "getEndpointsList",
      "id": "301f7b05-ec02-481b-9ed6-c07b97de2b7b"
}

Response:

{
  "result": {
    "total": 8,
    "page": 1,
    "perPage": 3,
    "pagesCount": 3,
    "hasMoreRecords": true,
    "items": [
      {
        "id": "64b7625d3c11463ef77e5d6d",
        "name": "string00:16:3e:7f:d3:2e",
        "label": "",
        "fqdn": "s0lc5.wkorh.dsd.ro",
        "groupId": "64b503c21ecee42e130a7bc9",
        "isManaged": true,
        "machineType": 1,
        "operatingSystemVersion": "Windows 7 Professional",
        "ip": "231.180.244.114",
        "macs": [
          "00:16:3e:7f:d3:2e"
        ],
        "ssid": "",
        "managedWithBest": true,
        "policy": {
          "id": "64b76bed92f0176fa203b64c",
          "name": "New Policy",
          "applied": false
        },
        "productOutdated": false,
        "lastSuccessfulScan": {
          "name": "72OHI5dnIH",
          "date": "2023-07-19T04:09:29+00:00"
        }
      }
    ]
  },
  "jsonrpc": "2.0",
  "id": "5986",
  "error": null
}

{
  "result": {
    "page": 2,
    "perPage": 3,
    "hasMoreRecords": true,
    "items": [
      {
       ...
      }
    ]
  },
  "jsonrpc": "2.0",
  "id": "5986",
  "error": null
}

Version 1.0

Parameters

Parameter	Type	Optional	Description
`parentId`	String	Yes	The ID of the target company or group. If not specified or set with a company ID, the method returns only the endpoints under Computers and Groups. Note To retrieve information on Active Directory endpoints, use the getNetworkInventoryItems method.
`isManaged`	Boolean	Yes	The flag to list managed or unmanaged endpoints. By default, the parameter is not set and the method returns all the managed and unmanaged endpoints. If set on `True`, the method returns only managed endpoints.
`page`	Number	Yes	The results page number. Default page number is 1.
`perPage`	Number	Yes	Number of items per page to be returned. The upper limit is 100 items per page. Default value: 30 items per page.
`filters`	Object	Yes	The filters to be used when querying the endpoints list. For information regarding the available filters and how to use them, refer to Available Filters.
`options`	Array	Yes	A set of options that control what information is present in the response.

Available Filters

You can use the filters parameter to query the endpoints by certain properties. Filters are structured in sections and subsections, described hereinafter

The query result is a list of endpoints that match ANY selected filter in ALL sections AND subsections.

These are the available filtering options:

Section	Subsection	Filtering Options
`security`	management	`managedWithBest` - a Boolean to filter all endpoints with the security agent installed on them. Default value: `False`. `managedExchangeServers` - a Boolean to filter all protected Exchange servers. Default value: `False`. This filter requires a valid license key that covers the security service. `managedRelays` - a Boolean to filter all endpoints with Relay role. Default value: `False`. `securityServers` - a Boolean to filter all Security Servers. Default value: `False`.
`depth`		`allItemsRecursively` - a Boolean to filter all endpoints recursively within the Network Inventory of a company. Default value: `False`.
`details`		`ssid` - string, the SSID (Active Directory SID of the endpoint) used to filter the endpoints regardless of their protection status. `macs` - array, the list of MAC addresses used to filter the endpoints regardless of their protection status. `name` - string, used for filtering the endpoints by name regardless of their protection status. Minimum required string length is three characters.

Important

Some filters require a specific license to be active, otherwise they are ignored, resulting in an inaccurate API response.

The field name works with partial matching.

The filter returns the endpoints whose names are exact match or start with the specified value. To use the specified value as a suffix, use the asterisk symbol (*).

For example:

If name is computer, the API returns all endpoints whose names start with computer.

If name is *puter, then the API returns a list of all endpoints that contain puter in their names.

Available options

You can use the options parameter to customize what information is included in the API response. Options are structured in sections and subsections, described hereinafter.

These are the available options:

Section	Description
`returnProductOutdated`	Boolean. If `true`, the `productOutdated` attribute is included in the API response.
`includeScanLogs`	Boolean. If true, the `lastSuccessfulScan` attribute is included in the API response. Default value: `false`.

Return value

This method returns an Object containing information about the endpoints. The returned object contains:

page - the current page
pagesCount - the total number of pages
perPage - the total number of returned items per page
total - the total number of items
items - an array containing the list of endpoints. Each entry in the list has the following fields:
- id, the ID of managed endpoint,
- name, the name of the endpoint,
- label, the label set to this endpoint,
- fqdn, the FQDN of the endpoint,
- groupId, the group ID of the endpoint,
- isManaged, boolean True, if this endpoint is managed,
- machineType, the type of the machine: (1 - computer, 2 - virtual machine, 3 - EC2 Instance, 0 - Other),
- operatingSystemVersion, the operating system version of the endpoint,
- ip, the IP address of the endpoint,
- macs, the MAC addresses of the endpoint,
- ssid, the SSID (Active Directory SID) of the endpoint,
- managedWithBest, boolean True, if BEST is installed on this endpoint,
- isContainerHost, boolean True, if this endpoint is a Container Host,
- managedExchangeServer, boolean True, if this endpoint is an Exchange Server,
- managedRelay, boolean True, if this endpoint has Relay role,
- securityServer, boolean True, if this endpoint is a Security Server,
- policy, an Object informing about the policy active on the endpoint. The object contains the following fields:
  - id - a String uniquely identifying the active policy,
  - name - the name of the policy,
  - applied - a Boolean set to True if the policy is currently applied on the endpoint,
movingInfo, an Object informing upon endpoint transfer from one company to another one. The object contains:
- state - the endpoint moving status (0 - in progress, 1 - moved),
- destinationCompanyName - the name of the company where the endpoint was moved.
productOutdated, boolean True, if the endpoint is missing one ore more agent updates.
lastSuccessfulScan, object. Includes the following details:
- name - the name of the scan.
- date - the date on which the scan was performed.

Example

Request:

{
      "params": {
           "parentId": "63c6bb02e3cb799758020b99",
           "page": 1,
           "perPage": 10,
           "filters": {
                   "security": {
                            "management": {
                                "managedWithBest": true,
                                "managedRelays": true
				}
                   }
		},
           "options": {
                   "returnProductOutdated": true,
                   "includeScanLogs": true
           }
      },
      "jsonrpc": "2.0",
      "method": "getEndpointsList",
      "id": "301f7b05-ec02-481b-9ed6-c07b97de2b7b"
}

Response:

{
  "result": {
    "total": 1,
    "page": 1,
    "perPage": 30,
    "pagesCount": 1,
    "items": [
      {
        "id": "64b7625d3c11463ef77e5d6d",
        "name": "string00:16:3e:7f:d3:2e",
        "label": "",
        "fqdn": "s0lc5.wkorh.dsd.ro",
        "groupId": "64b503c21ecee42e130a7bc9",
        "isManaged": true,
        "machineType": 1,
        "operatingSystemVersion": "Windows 7 Professional",
        "ip": "231.180.244.114",
        "macs": [
          "00:16:3e:7f:d3:2e"
        ],
        "ssid": "",
        "managedWithBest": true,
        "policy": {
          "id": "64b76bed92f0176fa203b64c",
          "name": "New Policy",
          "applied": false
        },
        "productOutdated": false,
        "lastSuccessfulScan": {
          "name": "72OHI5dnIH",
          "date": "2023-07-19T04:09:29+00:00"
        }
      }
    ]
  },
  "jsonrpc": "2.0",
  "id": "5986",
  "error": null
}

In this section:

getEndpointsList

Important

Parameters

Note

Available Filters

Important

Available options

Return value

Note

Note

Example

Version 1.0

Parameters

Note

Available Filters

Important

Available options

Return value

Example

Search results