getRegisteredDevices

POST public/getRegisteredDevices

Returns the devices registered at a location, with each device's current status from the site's edge security device (ESD). You can list every registered device, only the devices on one network segment, or one page of the list at a time.

Request syntax

curl https://apiv2.acumera.net/public/getRegisteredDevices \
  --cookie av_session.txt \
  --data-urlencode "location_id=<location_id>" \
  [--data-urlencode "segment=<segment_name>"] \
  [--data-urlencode "start=<offset>"] \
  [--data-urlencode "limit=<count>"]

Optional parameters are shown in brackets. The username, password, and tfa_token parameters are also accepted, and are required only if the client hasn't already signed in with login. See Getting started with the SC//AcuVigil API.

Request parameters

The request accepts the following parameters in a form-encoded body.

Parameter	Type	Description	Required	Default value
`location_id`	Integer	The ID of the location. To find location IDs, use getCompanyInfo with `include_sites=1`.	Yes
`segment`	String	Return only devices on this network segment, for example `POS`. Letters and numbers only, 1 to 12 characters. The segment must exist at the location.	No	All segments
`start`	Integer	The position in the list to start from. The first device is `0`.	No	`0`
`limit`	Integer	The maximum number of devices to return.	No	All devices

Response syntax

{
    "success": "string",
    "data": {
        "devices": [
            {
                "name": "string",
                "mac": "string",
                "ip": "string",
                "policy": "string",
                "handle": "string",
                "segment": "string",
                "device_type": "string",
                "status": "string",
                "message": "string",
                "vendor": "string"
            }
        ]
    }
}

Response parameters

If the call succeeds, success is "1" and the following data is returned. All values are strings.

Field	Description
`devices`	The registered devices, in the order the site stores them.
`devices[].name`	The name the device was registered with.
`devices[].mac`	The device's MAC address.
`devices[].ip`	The device's IP address.
`devices[].policy`	The firewall policy assigned to the device, for example `Local`. See Firewall policies.
`devices[].handle`	The device's error status: the status the device raises for the site if it stops responding, for example `CRITICAL`.
`devices[].segment`	The network segment the device is on.
`devices[].device_type`	The device type chosen at registration. Empty if none was chosen.
`devices[].status`	The device's current status from the ESD, for example `OK` or `CRITICAL`. `UNKNOWN` if the ESD hasn't reported the device.
`devices[].message`	A short description of the device's current state, for example `Responding` or `Not Responding`.
`devices[].vendor`	The manufacturer, looked up from the MAC address. `Unknown` if the manufacturer isn't recognized.

Errors

If the call fails, success is "0", and returnCode and returnMessage describe the problem. The HTTP status is still 200.

Return code	Message	Cause
`NO_LOCATION_SELECTED`	No location was selected or the location does not exist.	`location_id` is missing or isn't a number.
`LOCATION_NOT_FOUND`	The location was not found.	No location has that ID.
`AUTH_FAILED_FUNC_NOT_ALLOWED`	Authorization failed because you are not permitted to access the requested function.	Your account doesn't have access to the location.
`SITE_NOT_ACTIVE`	The location is not active.	The location isn't active.
`MG_TYPE_HARDWARE_NOT_FOUND`	No MG-type hardware is present at this location.	The location has no ESD.
`INVALID_SEGMENT_NAME`	The segment name is invalid.	`segment` contains characters other than letters and numbers, or is longer than 12 characters.
`SEGMENT_NOT_FOUND`	The specified segment was not found.	The location has no segment with that name.
`INVALID_START_PARAMETER`	The supplied start parameter is not numeric.	`start` isn't a number.
`INVALID_LIMIT_PARAMETER`	The supplied limit parameter is not numeric.	`limit` isn't a number.
`INVALID_LOGIN`	We were unable to log you in. Make sure you entered the correct username, password and 2FA code.	You haven't signed in, your session has ended, or the credentials sent with the call are wrong.

Examples

Example: Return the first devices at a location

This example returns the first five registered devices at location 4510.

curl https://apiv2.acumera.net/public/getRegisteredDevices \
  --cookie av_session.txt \
  --data-urlencode "location_id=4510" \
  --data-urlencode "limit=5"

Response (shortened to two devices):

{
    "success": "1",
    "data": {
        "devices": [
            {
                "name": "Office switch",
                "mac": "00:00:5E:00:53:20",
                "ip": "10.169.254.2",
                "policy": "Local",
                "handle": "CRITICAL",
                "segment": "Switch",
                "device_type": "",
                "status": "OK",
                "message": "Responding",
                "vendor": "Netgear"
            },
            {
                "name": "Back room switch",
                "mac": "00:00:5E:00:53:21",
                "ip": "10.169.254.3",
                "policy": "Local",
                "handle": "CRITICAL",
                "segment": "Switch",
                "device_type": "",
                "status": "CRITICAL",
                "message": "Not Responding",
                "vendor": "Netgear"
            }
        ]
    }
}

Example: Return only the devices on one segment

This example returns only the devices on the Switch segment.

curl https://apiv2.acumera.net/public/getRegisteredDevices \
  --cookie av_session.txt \
  --data-urlencode "location_id=4510" \
  --data-urlencode "segment=Switch"

Response (shortened to two devices):

{
    "success": "1",
    "data": {
        "devices": [
            {
                "name": "Office switch",
                "mac": "00:00:5E:00:53:20",
                "ip": "10.169.254.2",
                "policy": "Local",
                "handle": "CRITICAL",
                "segment": "Switch",
                "device_type": "",
                "status": "OK",
                "message": "Responding",
                "vendor": "Netgear"
            },
            {
                "name": "Back room switch",
                "mac": "00:00:5E:00:53:21",
                "ip": "10.169.254.3",
                "policy": "Local",
                "handle": "CRITICAL",
                "segment": "Switch",
                "device_type": "",
                "status": "CRITICAL",
                "message": "Not Responding",
                "vendor": "Netgear"
            }
        ]
    }
}

If the location has no segment with that name, the call fails:

{
    "success": "0",
    "returnCode": "SEGMENT_NOT_FOUND",
    "returnMessage": "The specified segment was not found."
}

Example: Page through a long device list

Use start and limit together to get the list in pages. The first device is at position 0. This example returns two devices starting at position 2, which are the third and fourth devices in the list.

curl https://apiv2.acumera.net/public/getRegisteredDevices \
  --cookie av_session.txt \
  --data-urlencode "location_id=4510" \
  --data-urlencode "start=2" \
  --data-urlencode "limit=2"

Response:

{
    "success": "1",
    "data": {
        "devices": [
            {
                "name": "Camera switch",
                "mac": "00:00:5E:00:53:22",
                "ip": "10.169.254.4",
                "policy": "Local",
                "handle": "CRITICAL",
                "segment": "Switch",
                "device_type": "",
                "status": "CRITICAL",
                "message": "Not Responding",
                "vendor": "Netgear"
            },
            {
                "name": "Register switch",
                "mac": "00:00:5E:00:53:23",
                "ip": "10.169.254.5",
                "policy": "Local",
                "handle": "CRITICAL",
                "segment": "Switch",
                "device_type": "",
                "status": "CRITICAL",
                "message": "Not Responding",
                "vendor": "Netgear"
            }
        ]
    }
}

To get the next page, increase start by the limit value. When a page returns fewer devices than limit, you've reached the end of the list.

Example: Call the function after your session has ended

If you haven't signed in, or your session has ended, every function returns INVALID_LOGIN. Sign in again with login and repeat the call.

{
    "success": "0",
    "returnCode": "INVALID_LOGIN",
    "returnMessage": "We were unable to log you in. Make sure you entered the correct username, password and 2FA code."
}