Inventory Device Serial

ManageThe inventoryInventory devicesDevice Serial API provides comprehensive device management capabilities through serial number-based operations. These endpoints enable you to manage network devices, monitor their status in real-time, and perform full CRUD operations usingon your device inventory using serial numbers as unique identifiers.

Base URL: https://control.zequenze.com/api/v1

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

---

Overview

The Inventory Device Serial API category is designed for managing network devices through their serial numbers, providing a robust interface for device inventory management, status monitoring, and configuration tracking. This API is particularly useful for network administrators, IT teams, and organizations that need to maintain comprehensive device inventories.

Key Features:

Device Lifecycle Management: Complete CRUD operations for device records Real-time Status Monitoring: Query device status with optional live updates Organization-based Filtering: Multi-tenant support with organization-level device segmentation Pending Configuration Tracking: Monitor devices with pending configuration changes Advanced Filtering: Filter by device type, status, organization, and status change timestamps

Common Use Cases:

Network inventory management and auditing Device status monitoring and alerting systems Automated device provisioning workflows Compliance reporting and device tracking Integration with network monitoring tools

The serial number serves as the primary identifier for individual device operations, making it ideal for hardware-based device management where serial numbers provide reliable unique identification.

---

Endpoints

GET /inventory_device_serial/

RetrieveDescription: Retrieves a paginated list of all inventory devices with optionalextensive filtering capabilities. This endpoint supports real-time status updates and comprehensive filtering options for efficient device discovery and monitoring across your infrastructure.

Use Cases:

Generate device inventory reports filtered by organization or device type Monitor device status changes within specific time ranges Build dashboards showing device distribution across organizations Identify devices with pending configuration changes

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_serial/?organization=123&status=true&limit=50&offset=0

Parameters:

Parameter	Type	In	Required	Description
type	integer	query	No	Filter devicedevices by device 'type'type ID field(e.g., router, switch, firewall)
status	string	query	No	Filter by device statusstatus. (Use '0', 'false', 'False' for Down;Down devices, or '1', 'true', 'True' for Up)Up devices
last_status_change_from	string	query	No	Filter bydevices with status changes after specified datetime in ISO format (2000-01-01, 2000-01-01 00:01:00, 2000-01-01 00:01:00+00:00)
organization	integer	query	No	Filter devicedevices by organization ID for multi-tenant environments
limit	integer	query	No	Number of results to return per page (default: 20, max: 100)
offset	integer	query	No	The initialStarting index fromfor whichpagination to(default: return results0)
pending	boolean	query	No	Report if the device hasInclude pending settingsconfiguration status in response
update_status	boolean	query	No	UsePerform configured helpers to update devicelive status check before returning informationdata (may increase response time)

ExamplecURL Request:Example:

curl -X GET "https://control.zequenze.com/api/v1/inventory_device_serial/?organization=123&status=true&organization=1pending=true&limit=1025" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "count": 25,247,
  "next": "https://control.zequenze.com/api/v1/inventory_device_serial/?limit=1025&offset=10"25&organization=123&status=true&pending=true",
  "previous": null,
  "results": [
    {
      "serial_number": "ABC123DEF456"SN123456789",
      "name": "Office Router Main"Core-Switch-01",
      "type": 1,{
        "id": 3,
        "name": "Network Switch",
        "model": "Cisco Catalyst 9300"
      },
      "organization": 1,{
        "id": 123,
        "name": "Acme Corp IT"
      },
      "status": true,
      "last_status_change": "2024-01-15T10:15T14:30:00Z"22Z",
      "pending_settings"ip_address": false,"192.168.1.10",
      "location": "Data Center A - Rack 15",
      "pending_changes": true,
      "created_at": "2024-01-10T09:01T09:00:00Z",
      "updated_at": "2024-01-15T10:15T14:30:00Z"22Z"
    }
  ]
}

Response Codes:

Status	Description
200	Success - Returns paginated device list
401	Unauthorized - Invalid or missing API token

403 Forbidden - Insufficient permissions for organization filter

---

POST /inventory_device_serial/

CreateDescription: Creates a new device record in the inventory device.system. This endpoint allows you to register new devices with complete configuration details, automatically generating tracking records for lifecycle management.

Use Cases:

Register newly purchased or deployed devices Bulk import devices from procurement systems Automated device registration during provisioning Integration with asset management systems

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_serial/

Parameters:

Parameter	Type	In	Required	Description
data	stringobject	body	Yes	JSON payload containingComplete device information including serial number, type, organization, and configuration details

ExamplecURL Request:Example:

curl -X POST "https://control.zequenze.com/api/v1/inventory_device_serial/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/jsonjson" \
  -d '{
    "serial_number": "XYZ789GHI012"SN987654321",
    "name": "New Branch Router"Edge-Router-05",
    "type": 2,1,
    "organization": 1,123,
    "ip_address": "192.168.2.5",
    "location": "Branch Office B",
    "status": truetrue,
    "description": "Primary edge router for branch connectivity"
  }'

Example Response:

{
  "serial_number": "XYZ789GHI012"SN987654321",
  "name": "New Branch Router"Edge-Router-05",
  "type": 2,{
    "id": 1,
    "name": "Router",
    "model": "Cisco ISR 4331"
  },
  "organization": 1,{
    "id": 123,
    "name": "Acme Corp IT"
  },
  "ip_address": "192.168.2.5",
  "location": "Branch Office B",
  "status": true,
  "last_status_change"description": "2024-01-16T14:20:00Z"Primary edge router for branch connectivity",
  "pending_settings"pending_changes": false,
  "created_at": "2024-01-16T14:20:00Z"16T10:15:30Z",
  "updated_at": "2024-01-16T14:20:00Z"16T10:15:30Z"
}

Response Codes:

Status	Description
201	Created - Device successfully registered
400	Bad requestRequest - Invalid data or missing required fields
401409	UnauthorizedConflict - Device with this serial number already exists

---

GET /inventory_device_serial/{serial_number}/

RetrieveDescription: detailsRetrieves ofdetailed information for a specific inventory device identified by its serial number. Supports optional real-time status updates and pending configuration reporting for comprehensive device monitoring.

Use Cases:

Get complete device details for troubleshooting Verify device configuration and status before maintenance Integration with monitoring systems for device health checks Audit trail and compliance reporting for specific devices

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_serial/SN123456789/?update_status=true&pending=true

Parameters:

Parameter	Type	In	Required	Description
serial_number	string	path	Yes	DeviceUnique serial number of the device to retrieve
pending	boolean	query	No	ReportInclude if the device hasdetailed pending settingsconfiguration information
update_status	boolean	query	No	UsePerform configuredlive helpersstatus check to updateget real-time device status before returning informationstate

ExamplecURL Request:Example:

curl -X GET "https://control.zequenze.com/api/v1/inventory_device_serial/ABC123DEF456/SN123456789/?update_status=true&pending=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "serial_number": "ABC123DEF456"SN123456789",
  "name": "Office Router Main"Core-Switch-01",
  "type": 1,{
    "id": 3,
    "name": "Network Switch",
    "model": "Cisco Catalyst 9300",
    "manufacturer": "Cisco"
  },
  "organization": 1,{
    "id": 123,
    "name": "Acme Corp IT",
    "code": "ACME-IT"
  },
  "status": true,
  "last_status_change": "2024-01-15T10:15T14:30:00Z"22Z",
  "pending_settings"ip_address": "192.168.1.10",
  "mac_address": "00:1B:44:11:3A:B7",
  "location": "Data Center A - Rack 15",
  "description": "Primary core switch for data center connectivity",
  "firmware_version": "16.12.05",
  "pending_changes": true,
  "pending_details": {
    "configuration_updates": 3,
    "firmware_update": false,
    "last_pending_change": "2024-01-16T08:45:00Z"
  },
  "created_at": "2024-01-10T09:01T09:00:00Z",
  "updated_at": "2024-01-15T10:30:16T08:45:00Z"
}

Response Codes:

Status	Description
200	Success - Returns complete device information
404	DeviceNot notFound - No device found with specified serial number
401	Unauthorized - Invalid or missing API token

---

PUT /inventory_device_serial/{serial_number}/

CompletelyDescription: Performs a complete update anof existinga device record, replacing all modifiable fields with the provided data. This endpoint is ideal for comprehensive device updates during major configuration changes or asset management updates.

Use Cases:

Complete device reconfiguration after hardware changes Asset management updates when devices are relocated or repurposed Bulk updates from external inventory device.management systems Major configuration changes requiring full record updates

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_serial/SN123456789/

Parameters:

Parameter	Type	In	Required	Description
serial_number	string	path	Yes	Device serialSerial number of the device to update
data	stringobject	body	Yes	JSON payload containing completeComplete device informationdata object with all required fields

ExamplecURL Request:Example:

curl -X PUT "https://control.zequenze.com/api/v1/inventory_device_serial/ABC123DEF456/SN123456789/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/jsonjson" \
  -d '{
  "serial_number": "ABC123DEF456",
    "name": "Updated Office Router"Core-Switch-01-Updated",
    "type": 1,3,
    "organization": 2,123,
    "ip_address": "192.168.1.15",
    "location": "Data Center A - Rack 16",
    "status": falsetrue,
    "description": "Updated primary core switch with new configuration",
    "firmware_version": "16.12.06"
  }'

Example Response:

{
  "serial_number": "ABC123DEF456"SN123456789",
  "name": "Updated Office Router"Core-Switch-01-Updated",
  "type": 1,{
    "id": 3,
    "name": "Network Switch",
    "model": "Cisco Catalyst 9300"
  },
  "organization": 2,{
    "id": 123,
    "name": "Acme Corp IT"
  },
  "ip_address": "192.168.1.15",
  "location": "Data Center A - Rack 16",
  "status": false,true,
  "last_status_change"description": "2024-01-16T15:45:00Z"Updated primary core switch with new configuration",
  "pending_settings": true,
  "created_at"firmware_version": "2024-01-10T09:00:00Z"16.12.06",
  "pending_changes": false,
  "updated_at": "2024-01-16T15:45:00Z"16T11:20:15Z"
}

Response Codes:

Status	Description
200	UpdatedSuccess successfully

- 404 Device notcompletely foundupdated 400 Bad requestRequest - Invalid data or missing required fields 401404 UnauthorizedNot Found - Device with specified serial number not found

---

PATCH /inventory_device_serial/{serial_number}/

PartiallyDescription: Performs a partial update anof existinga inventorydevice device.record, modifying only the specified fields while leaving other attributes unchanged. This endpoint is perfect for targeted updates like status changes, location updates, or individual field modifications.

Use Cases:

Update device location during relocations Change device status during maintenance windows Update specific configuration parameters Incremental updates from monitoring systems

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_serial/SN123456789/

Parameters:

Parameter	Type	In	Required	Description
serial_number	string	path	Yes	Device serialSerial number of the device to partially update
data	stringobject	body	Yes	JSON payloadObject containing only the fields to updatebe updated

ExamplecURL Request:Example:

curl -X PATCH "https://control.zequenze.com/api/v1/inventory_device_serial/ABC123DEF456/SN123456789/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/jsonjson" \
  -d '{
  "name": "Partially Updated Router",
    "status": truefalse,
    "description": "Device offline for scheduled maintenance"
  }'

Example Response:

{
  "serial_number": "ABC123DEF456"SN123456789",
  "name": "Partially Updated Router"Core-Switch-01-Updated",
  "type": 1,{
    "id": 3,
    "name": "Network Switch",
    "model": "Cisco Catalyst 9300"
  },
  "organization": 2,{
    "id": 123,
    "name": "Acme Corp IT"
  },
  "ip_address": "192.168.1.15",
  "location": "Data Center A - Rack 16",
  "status": true,false,
  "description": "Device offline for scheduled maintenance",
  "firmware_version": "16.12.06",
  "pending_changes": false,
  "last_status_change": "2024-01-16T16:00:00Z",
  "pending_settings": false,
  "created_at": "2024-01-10T09:00:00Z"16T12:05:33Z",
  "updated_at": "2024-01-16T16:00:00Z"16T12:05:33Z"
}

Response Codes:

Status	Description
200	UpdatedSuccess successfully

- 404 Device notpartially foundupdated 400 Bad requestRequest - Invalid field values 401404 UnauthorizedNot Found - Device with specified serial number not found

---

DELETE /inventory_device_serial/{serial_number}/

DeleteDescription: anPermanently existingremoves a device record from the inventory device.system. This operation is irreversible and should be used when devices are decommissioned, disposed of, or no longer part of the managed infrastructure.

Use Cases:

Remove decommissioned devices from active inventory Clean up test devices after project completion Asset disposal and end-of-life device management Inventory cleanup during system migrations

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_serial/SN123456789/

Parameters:

Parameter	Type	In	Required	Description
serial_number	string	path	Yes	Device serialSerial number of the device to delete

ExamplecURL Request:Example:

curl -X DELETE "https://control.zequenze.com/api/v1/inventory_device_serial/ABC123DEF456/SN123456789/" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response Codes:

Status	Description
204	DeletedNo Content - Device successfully deleted
404	Not Found - Device with specified serial number not found
401403	UnauthorizedForbidden - Insufficient permissions to delete this device

---

Common Use Cases

Use Case 1: Real-time Infrastructure Monitoring

Monitor device status across your network infrastructure by combining the list endpoint with status filtering and live updates. Use GET /inventory_device_serial/?status=false&update_status=true to identify offline devices and trigger automated alerts or maintenance workflows.

Use Case 2: Multi-tenant Device Management

Manage devices across multiple organizations by leveraging organization filtering. Use GET /inventory_device_serial/?organization={org_id} to segment device management for different clients or business units while maintaining centralized control.

Use Case 3: Automated Device Provisioning

Integrate device registration into your provisioning workflow using POST operations to automatically register new devices as they're deployed, followed by PATCH operations to update status and configuration as provisioning progresses.

Use Case 4: Maintenance Window Management

Use the PATCH endpoint to update device status and descriptions during maintenance windows, providing clear visibility into which devices are offline for scheduled maintenance versus unexpected outages.

Use Case 5: Configuration Change Tracking

Leverage the pending=true parameter to monitor devices with pending configuration changes, enabling proactive management of configuration deployment and validation workflows.

---

Best Practices

• Pagination: Always use appropriate limit values (recommended: 25-100) for list operations to ensure optimal performance and prevent timeouts

Real-time Updates: Use the update_statusupdate_status=true parameterjudiciously, whenas youit needcan real-timesignificantly increase response times for large device status informationlists Error Handling: Implement properrobust error handling for device not found scenarios (404 responses) Use pagination parameters (limit and offset) for large device inventories to improve performance Filter by organizationresponses when working inwith multi-tenantserial environmentsnumbers, toas scopedevices resultsmay appropriatelybe removed or serial numbers may be mistyped Check theRate pending_settingsLimiting: fieldImplement toappropriate identifydelays devicesbetween thatrequests requirewhen configurationperforming updatesbulk Use PATCH for partial updatesoperations to avoid overwritingoverwhelming unchangedthe fieldsAPI Serial Data Validation: Always validate serial numbers areand case-sensitiverequired identifiersfields -before ensuremaking exactrequests matchesto whenprevent queryingunnecessary API calls Caching: Cache device type and organization data locally to reduce the need for additional API calls during device operations Security: Never log or store API tokens in plain text, and use environment variables or secure credential management systems Filtering Strategy: Use specific devicesfilters (organization, type, status) to reduce payload sizes and improve response times for targeted queries