Jump to

• Request
• Response

Create a Device

post

/api/device/Devices

Creates a new device.
For physical devices, at minimum, you must specify either the Custom Name, DNS Name, IPv4 or IPv6 address.
For virtual devices, IP address and DNS name are not used. Only Custom Name and Parent Device are required.
The minimum required properties in the request body are:

• DeviceStateID
• DNSName
• For virtual devices (when DeviceStateID is set to 102):
  • CustomName
  • Either of the following:
    • ParentDeviceName
    • ParentDeviceID
• For physical devices, any of the following:
  • Custom Name
  • DNS Name
  • IPAddress
  • IPv6Address
• DevicePriorityID
• DeviceZoneID
• DeviceTypeCategoryID
• ShardID (defaults to 1 if not specified, but specify it if you are using database shards)
• MetaData

Note: Previously, either IPv4 or IPv6 was required. These have been deprecated. Use IPAddress or IPv6Address instead.

Request

There are no request parameters for this operation.

Supported Media Types

• application/json

Request Body - application/json ()

Root Schema : schema

Type: object

Show Source

• CustomName: string
  The device custom name. Sequences of integers optionally prefixed by a sign character, such as 12345, +123, -456, or 0888 are not supported. Hexadecimal, decimal, and exponential expressions are valid and are treated as a name. For example, 0xAD, 123e10, 33.44.
• DevicePriorityID: integer
  The device priority ID.
• DeviceSNMPAccessID: integer
  The SNMP access profile ID.
• DeviceStateID: integer
  Allowed Values: [ 0, 1, 2, 3, 101, 102 ]

  The device state ID. Valid values are:

  • 0: New
  • 1: Non-discoverable
  • 2: Verified (Discovered)
  • 3: Discovered (Fully)
  • 101: Static (Disabled)
  • 102: Virtual (Non-device)
• DeviceTypeCategoryID: integer
  The device type category ID.
• DeviceZoneID: integer
  The device zone ID.
• DNSName: string
  The device DNS name. Sequences of integers optionally prefixed by a sign character, such as 12345, +123, -456, or 0888 are not supported. Hexadecimal, decimal, and exponential expressions are valid and are treated as a name. For example, 0xAD, 123e10, 33.44.
• GeoLocation: string
  The GeoJSON point of device location (lon, lat).
• InitialDeviceGroupID: integer
  The initial device group ID.
• IPv4: string
  The IPv4 address.
• IPv6: string
  The IPv6 address in hex notation.
• MetaData: array MetaData
  The metadata object definitions for the device (DeviceMetaTypeID, MetaData).
• ParentDeviceID: integer
  The parent device ID for virtual devices.
• ShardID: integer
  The device shard ID. If database sharding is not configured, it defaults to 1.

{
    "properties":{
        "DNSName":{
            "description":"The device DNS name. Sequences of integers optionally prefixed by a sign character, such as <b>12345</b>, <b>+123</b>, <b>-456</b>, or <b>0888</b> are not supported. Hexadecimal, decimal, and exponential expressions are valid and are treated as a name. For example, <b>0xAD</b>, <b>123e10</b>, <b>33.44</b>.",
            "type":"string"
        },
        "DeviceStateID":{
            "description":"The device state ID. Valid values are:\n<ul>\n<li><b>0</b>: New</li>\n<li><b>1</b>: Non-discoverable</li>\n<li><b>2</b>: Verified (Discovered)</li>\n<li><b>3</b>: Discovered (Fully)</li>\n<li><b>101</b>: Static (Disabled)</li>\n<li><b>102</b>: Virtual (Non-device)</li>\n</ul>",
            "type":"integer",
            "enum":[
                0,
                1,
                2,
                3,
                101,
                102
            ]
        },
        "IPv4":{
            "description":"The IPv4 address.",
            "type":"string"
        },
        "IPv6":{
            "description":"The IPv6 address in hex notation.",
            "type":"string"
        },
        "DevicePriorityID":{
            "description":"The device priority ID.",
            "type":"integer"
        },
        "CustomName":{
            "description":"The device custom name. Sequences of integers optionally prefixed by a sign character, such as <b>12345</b>, <b>+123</b>, <b>-456</b>, or <b>0888</b> are not supported. Hexadecimal, decimal, and exponential expressions are valid and are treated as a name. For example, <b>0xAD</b>, <b>123e10</b>, <b>33.44</b>.",
            "type":"string"
        },
        "DeviceZoneID":{
            "description":"The device zone ID.",
            "type":"integer"
        },
        "DeviceTypeCategoryID":{
            "description":"The device type category ID.",
            "type":"integer"
        },
        "InitialDeviceGroupID":{
            "description":"The initial device group ID.",
            "type":"integer"
        },
        "DeviceSNMPAccessID":{
            "description":"The SNMP access profile ID.",
            "type":"integer"
        },
        "ParentDeviceID":{
            "description":"The parent device ID for virtual devices.",
            "type":"integer"
        },
        "GeoLocation":{
            "description":"The GeoJSON point of device location (lon, lat).",
            "type":"string"
        },
        "MetaData":{
            "description":"The metadata object definitions for the device (DeviceMetaTypeID, MetaData).",
            "type":"array",
            "items":{
                "type":"object"
            }
        },
        "ShardID":{
            "description":"The device shard ID. If database sharding is not configured, it defaults to 1.",
            "type":"integer"
        }
    },
    "type":"object"
}

Nested Schema : MetaData

Type: array

The metadata object definitions for the device (DeviceMetaTypeID, MetaData).

Show Source

• Array of: object items

{
    "description":"The metadata object definitions for the device (DeviceMetaTypeID, MetaData).",
    "type":"array",
    "items":{
        "type":"object"
    }
}

Nested Schema : items

Type: object

Back to Top

Response

200 Response

Successful operation

Body ()

Root Schema : SuccessfulAddOperation

Type: object

The response body for a successful add operation.

Show Source

• message: string
  The response message.

  Example: Added record
• success: boolean
  Whether the operation was a success (true) or a failure (false).

  Example: true

{
    "description":"The response body for a successful add operation.",
    "properties":{
        "success":{
            "description":"Whether the operation was a success (<b>true</b>) or a failure (<b>false</b>).",
            "type":"boolean",
            "example":"true"
        },
        "message":{
            "description":"The response message.",
            "type":"string",
            "example":"Added record"
        }
    },
    "type":"object"
}

Default Response

Failed operation

Body ()

Root Schema : schema

Type: object

Show Source

• errors: array errors
  The list of errors reported. Validation errors will be keyed by record field.
• message: string
  The response message.

  Example: Exception thrown
• success: boolean
  Whether the operation was a success (true) or a failure (false).

  Example: false

{
    "properties":{
        "success":{
            "description":"Whether the operation was a success (<b>true</b>) or a failure (<b>false</b>).",
            "type":"boolean",
            "example":"false"
        },
        "message":{
            "description":"The response message.",
            "type":"string",
            "example":"Exception thrown"
        },
        "errors":{
            "description":"The list of errors reported. Validation errors will be keyed by record field.",
            "type":"array",
            "items":{
                "description":"An error.",
                "type":"object"
            }
        }
    },
    "type":"object"
}

Nested Schema : errors

Type: array

The list of errors reported. Validation errors will be keyed by record field.

Show Source

• Array of: object items
  An error.

{
    "description":"The list of errors reported. Validation errors will be keyed by record field.",
    "type":"array",
    "items":{
        "description":"An error.",
        "type":"object"
    }
}

Nested Schema : items

Type: object

An error.

Back to Top