Identify a list of devices and networks

SecurityApiKeyAuth or JWTAuth
Request
Request Body schema: application/json

List of devices and networks. MUST be encoded in JSON format.

Array of objects (InputNetwork)
required
Array of objects (InputDevice)
object (EndpointInfo)

The endpoint info object is optional in DevRecogQuery.

It SHOULD be used only for E2C (endpoint to cloud) integrations for providing to Fing cloud some information about the calling endpoint.

Responses
200

OK

The request has been fulfilled successfully.

The response body MUST contain the response object.

The response MIGHT NOT provide a proper identification for some or any devices. A new request with same input data SHOULD NOT be redone within 48 hours.

400

BAD REQUEST

The request comes with a wrong input. The code is returned in threee different cases:

  • Missing Payload

    There is no input.

  • Malformed Payload

    The input is malformed.

  • No device to recognise

    The devices' list is empty. A valid request needs at least one.

Look to DevRecogQuery schema to understand how to compose a valid input.

401

UNAUTHORIZED

The request needs to be authenticated in some way. Available methods:

  • API Key
  • JWT Token

Please look at Authentication section for further information. You SHOULD redo the request with the proper authentication key/token.

402

PAYMENT REQUIRED

The Device Identification API is part of a paid service. Depending on the license agreement in place, it might happen that the request exceeds the existing limit. The most common ones are:

  1. Number of Calls

The number of calls is a counter that monitors the authorized request made to the recognition endpoint on a monthly basis.

POST /dis/3/devrecog
  1. Number of Devices

The number of devices is a counter that monitors the input devices on a monthly basis.

As a matter of example, if you made this request:

{
  "devices": [
    {"mac": "F4:F5:D8:EA:24:F8",
     "dhcp": {"params": "53,50,57,60,12,55,255"}},
    {"mac": "00:11:32:0A:89:DF",
     "hua": [{"userAgent": "synology_armada375_ds215j DSM6.0-8754 Update 8 (synoagentregisterd_dsm)"}]}
  ]
}

it increases the number of monthly calls by 1 and the number of requested devices by 2.

  1. Number of Credits

The number of credits is a counter that keeps track of the total of enriched devices. An "enrich device" is an input device for which Fing has sent back an identification ("recognition" field). See DevRecogResponse for further information.

403

FORBIDDEN

The authenticated license does not have enough permission to access the api. The most common reason is the expiration of the license

You MUST not redo the request until the issue has been sanitised.

500

INTERNAL SERVER ERROR

Something went wrong. This is the standard code for generic error.

503

SERVICE UNAVAILABLE

The server is running in overloading condition and discard some request.

post/devrecog
Request samples
application/json

Bootstrap example with only mandatory fields. All basic requirements are met:

  • devices field MUST be a not-empty JSON array of JSON object
  • the device object MUST contain at least the mac field with a valid MAC address
{
  • "devices": [
    ]
}
Response samples
application/json
{
  • "devices": [
    ]
}