Skip to main content

Inventory Device Serial

The Inventory Device 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 on 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/

Description: Retrieves a paginated list of all inventory devices with extensive 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 devices by device type ID (e.g., router, switch, firewall)
status string query No Filter by device status. Use '0', 'false', 'False' for Down devices, or '1', 'true', 'True' for Up devices
last_status_change_from string query No Filter devices 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 devices by organization ID for multi-tenant environments
limit integer query No Number of results per page (default: 20, max: 100)
offset integer query No Starting index for pagination (default: 0)
pending boolean query No Include pending configuration status in response
update_status boolean query No Perform live status check before returning data (may increase response time)

cURL Example:

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

Example Response:

{
  "count": 247,
  "next": "https://control.zequenze.com/api/v1/inventory_device_serial/?limit=25&offset=25&organization=123&status=true&pending=true",
  "previous": null,
  "results": [
    {
      "serial_number": "SN123456789",
      "name": "Core-Switch-01",
      "type": {
        "id": 3,
        "name": "Network Switch",
        "model": "Cisco Catalyst 9300"
      },
      "organization": {
        "id": 123,
        "name": "Acme Corp IT"
      },
      "status": true,
      "last_status_change": "2024-01-15T14:30:22Z",
      "ip_address": "192.168.1.10",
      "location": "Data Center A - Rack 15",
      "pending_changes": true,
      "created_at": "2024-01-01T09:00:00Z",
      "updated_at": "2024-01-15T14:30: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/

Description: Creates a new device record in the inventory 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 object body Yes Complete device information including serial number, type, organization, and configuration details

cURL Example:

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

Example Response:

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

Response Codes:

Status Description
201 Created - Device successfully registered
400 Bad Request - Invalid data or missing required fields
409 Conflict - Device with this serial number already exists

GET /inventory_device_serial/{serial_number}/

Description: Retrieves detailed information for a specific 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 Unique serial number of the device to retrieve
pending boolean query No Include detailed pending configuration information
update_status boolean query No Perform live status check to get real-time device state

cURL Example:

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

Example Response:

{
  "serial_number": "SN123456789",
  "name": "Core-Switch-01",
  "type": {
    "id": 3,
    "name": "Network Switch",
    "model": "Cisco Catalyst 9300",
    "manufacturer": "Cisco"
  },
  "organization": {
    "id": 123,
    "name": "Acme Corp IT",
    "code": "ACME-IT"
  },
  "status": true,
  "last_status_change": "2024-01-15T14:30:22Z",
  "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-01T09:00:00Z",
  "updated_at": "2024-01-16T08:45:00Z"
}

Response Codes:

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

PUT /inventory_device_serial/{serial_number}/

Description: Performs a complete update of a 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 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 Serial number of the device to update
data object body Yes Complete device data object with all required fields

cURL Example:

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

Example Response:

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

Response Codes:

Status Description
200 Success - Device completely updated
400 Bad Request - Invalid data or missing required fields
404 Not Found - Device with specified serial number not found

PATCH /inventory_device_serial/{serial_number}/

Description: Performs a partial update of a 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 Serial number of the device to partially update
data object body Yes Object containing only the fields to be updated

cURL Example:

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

Example Response:

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

Response Codes:

Status Description
200 Success - Device partially updated
400 Bad Request - Invalid field values
404 Not Found - Device with specified serial number not found

DELETE /inventory_device_serial/{serial_number}/

Description: Permanently removes a device record from the inventory 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 Serial number of the device to delete

cURL Example:

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

Response Codes:

Status Description
204 No Content - Device successfully deleted
404 Not Found - Device with specified serial number not found
403 Forbidden - 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 update_status=true judiciously, as it can significantly increase response times for large device lists
  • Error Handling: Implement robust error handling for 404 responses when working with serial numbers, as devices may be removed or serial numbers may be mistyped
  • Rate Limiting: Implement appropriate delays between requests when performing bulk operations to avoid overwhelming the API
  • Data Validation: Always validate serial numbers and required fields before making requests to prevent unnecessary 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 filters (organization, type, status) to reduce payload sizes and improve response times for targeted queries
Back to top