getUnregisteredDevices

POST public/getUnregisteredDevices

Returns the devices the site's edge security device (ESD) sees on the network that aren't registered. Use it to find unknown devices, or devices waiting to be registered. You can list all unregistered devices or only those on one network segment.

Request syntax

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

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

Response syntax

{
    "success": "string",
    "data": {
        "unregistered_devices": [
            {
                "status": "string",
                "mac": "string",
                "ip": "string",
                "segment": "string",
                "message": "string",
                "name": "string",
                "vendor": "string"
            }
        ]
    }
}

Response parameters

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

Field	Description
`unregistered_devices`	The unregistered devices the ESD currently sees.
`unregistered_devices[].status`	The device's status, for example `CRITICAL`.
`unregistered_devices[].mac`	The device's MAC address.
`unregistered_devices[].ip`	The device's IP address.
`unregistered_devices[].segment`	The network segment the device is on.
`unregistered_devices[].message`	A short description of the device's current state, for example `Responding`.
`unregistered_devices[].name`	The name the device announces on the network. Empty if the device doesn't announce a name.
`unregistered_devices[].vendor`	The manufacturer, looked up from the MAC address. `Unknown` if the manufacturer isn't recognized.

To register a device, see registerDevices, or register it in the dashboard. See Registering new devices.

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_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 all unregistered devices at a location

This example returns every unregistered device at location 4510.

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

Response (shortened to two devices):

{
    "success": "1",
    "data": {
        "unregistered_devices": [
            {
                "status": "CRITICAL",
                "mac": "00:00:5E:00:53:22",
                "ip": "10.169.254.27",
                "segment": "Switch",
                "message": "Responding",
                "name": "",
                "vendor": "Netgear"
            },
            {
                "status": "CRITICAL",
                "mac": "00:00:5E:00:53:23",
                "ip": "10.169.254.192",
                "segment": "Switch",
                "message": "Responding",
                "name": "",
                "vendor": "Netgear"
            }
        ]
    }
}

Example: Return unregistered devices on one segment

This example returns only the unregistered devices on the Switch segment. The response has the same format, and lists only devices whose segment is Switch.

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