Inventory Device Serial

The inventory_device_serial endpoints provide comprehensive device management capabilities for inventory systems, allowing you to perform CRUD operations on devices using their serial numbers as identifiers. These endpoints are essential for device lifecycle management, status monitoring, and remote device operations in enterprise environments.

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 provides a complete set of endpoints for managing network devices and equipment through their serial numbers. This API is designed for organizations that need to track, monitor, and control devices across their infrastructure.

Key Capabilities:

Device Discovery & Registration: Create and register new devices in your inventory
Status Monitoring: Real-time device status tracking with filtering capabilities
Remote Operations: Execute device operations like reboots, factory resets, and configuration synchronization
Location Management: Track device locations with GPS coordinates and location hierarchies
Firmware Management: Handle firmware upgrades and version tracking
CWMP/TR-069 Integration: Full support for device management protocols

Common Integration Scenarios:

Network operations centers monitoring device health
Field service applications tracking equipment deployments
Automated device provisioning and configuration management
Asset management systems requiring real-time device status
Remote troubleshooting and maintenance operations

Endpoints

GET /inventory_device_serial/

Description: Retrieves a paginated list of all devices in your inventory with powerful filtering capabilities. This endpoint is the primary way to discover and monitor devices across your organization, providing comprehensive device information including status, location, and configuration details.

Use Cases:

Dashboard applications showing device fleet overview
Monitoring systems checking device health across locations
Reports filtering devices by status, type, or organization
Bulk operations identifying devices needing updates

Full URL Example:

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

Parameters:

Parameter	Type	In	Required	Description
type	integer	query	No	Filter devices by device type ID (device profile/template)
status	string	query	No	Filter by device status. Use '0'/'false'/'False' for Down devices, '1'/'true'/'True' for Up devices
last_status_change_from	string	query	No	Filter devices with status changes after this datetime (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
limit	integer	query	No	Number of results per page (default pagination limit applies)
offset	integer	query	No	Starting index for pagination (use with limit for paging)
pending	boolean	query	No	Include pending settings information in the response
update_status	boolean	query	No	Refresh device status from configured helpers before returning data

cURL Example:

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

Example Response:

{
  "count": 245,
  "next": "https://control.zequenze.com/api/v1/inventory_device_serial/?limit=20&offset=20&organization=123&status=true",
  "previous": null,
  "results": [
    {
      "id": 1001,
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Router-Branch-Office-01",
      "customer_id": "CUST-001-RTR",
      "is_active": true,
      "status": "Up",
      "status_change": "2024-01-15T08:30:00Z",
      "type": 5,
      "type_short_name": "enterprise-router",
      "software_version": "15.1.4",
      "hardware_version": "2.1",
      "manufacturer": "Cisco Systems",
      "unique_identifier": "cisco-2921-router",
      "product_class": "Router",
      "serial_number": "FCZ1234567890",
      "serial_number_alt": "ALT-FCZ1234567890",
      "description": "Main router for branch office network infrastructure",
      "organization_id": 123,
      "firmware_image": 42,
      "firmware_image_is_pending": false,
      "location_name": "Branch Office - Network Room",
      "location": 15,
      "location_short_name": "branch-01-netroom",
      "latitude": "40.7128",
      "longitude": "-74.0060",
      "username": "device_agent_001",
      "update_frequency": 300,
      "address": "192.168.1.1",
      "last_connection": "2024-01-15T14:22:00Z",
      "last_configuration": "2024-01-15T09:15:00Z",
      "last_change": "2024-01-15T09:15:00Z",
      "created": "2024-01-10T16:45:00Z",
      "debug": false,
      "pending_settings": "None"
    }
  ]
}

Response Codes:

Status	Description
200	Success - Returns paginated device list
401	Unauthorized - Invalid or missing API token
403	Forbidden - Insufficient permissions for requested organization
400	Bad Request - Invalid filter parameters

POST /inventory_device_serial/

Description: Creates a new device record in your inventory system. This endpoint is used during device onboarding, allowing you to register new devices with their configuration, location, and management settings before they come online.

Use Cases:

Bulk device provisioning during network deployments
Pre-registering devices before field installation
Automated device discovery and registration workflows
Integration with procurement systems adding new equipment

Full URL Example:

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

Parameters:

Parameter	Type	In	Required	Description
data	object	body	Yes	Complete device object with required and optional fields

Request Body Example:

{
  "name": "Switch-Floor-2-East",
  "customer_id": "CUST-002-SW",
  "is_active": true,
  "type": 3,
  "serial_number": "SN-SW-987654321",
  "serial_number_alt": "ALT-987654321",
  "description": "48-port access switch for second floor east wing",
  "organization_id": 123,
  "location_name": "Building A - Floor 2 - Network Closet",
  "location": 22,
  "latitude": "40.7589",
  "longitude": "-73.9851",
  "username": "switch_agent_002",
  "password": "SecurePassword123!",
  "update_frequency": 600
}

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 '{
    "name": "Switch-Floor-2-East",
    "customer_id": "CUST-002-SW",
    "is_active": true,
    "type": 3,
    "serial_number": "SN-SW-987654321",
    "description": "48-port access switch for second floor east wing",
    "organization_id": 123,
    "location": 22,
    "username": "switch_agent_002",
    "password": "SecurePassword123!",
    "update_frequency": 600
  }'

Example Response:

{
  "id": 1002,
  "uuid": "660f9511-f3ac-52e5-b827-557766551111",
  "name": "Switch-Floor-2-East",
  "customer_id": "CUST-002-SW",
  "is_active": true,
  "status": "Down",
  "status_change": null,
  "type": 3,
  "type_short_name": "access-switch",
  "serial_number": "SN-SW-987654321",
  "serial_number_alt": "ALT-987654321",
  "description": "48-port access switch for second floor east wing",
  "organization_id": 123,
  "location": 22,
  "location_short_name": "bldg-a-floor-2",
  "latitude": "40.7589",
  "longitude": "-73.9851",
  "username": "switch_agent_002",
  "update_frequency": 600,
  "created": "2024-01-15T15:30:00Z",
  "debug": false,
  "pending_settings": "None"
}

Response Codes:

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

GET /inventory_device_serial/{serial_number}/

Description: Retrieves detailed information for a specific device using its serial number as the identifier. This endpoint provides complete device details including current status, configuration, and operational data.

Use Cases:

Device detail pages in management interfaces
Troubleshooting workflows requiring specific device information
Status checks for individual devices during maintenance
Integration with monitoring systems tracking specific equipment

Full URL Example:

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

Parameters:

Parameter	Type	In	Required	Description
serial_number	string	path	Yes	The serial number of the device to retrieve
pending	boolean	query	No	Include pending settings information in the response
update_status	boolean	query	No	Refresh device status from configured helpers before returning data

cURL Example:

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

Example Response:

{
  "id": 1001,
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Router-Branch-Office-01",
  "customer_id": "CUST-001-RTR",
  "is_active": true,
  "status": "Up",
  "status_change": "2024-01-15T08:30:00Z",
  "type": 5,
  "type_short_name": "enterprise-router",
  "software_version": "15.1.4",
  "hardware_version": "2.1",
  "manufacturer": "Cisco Systems",
  "unique_identifier": "cisco-2921-router",
  "product_class": "Router",
  "serial_number": "FCZ1234567890",
  "description": "Main router for branch office network infrastructure",
  "organization_id": 123,
  "firmware_image": 42,
  "firmware_image_is_pending": false,
  "location_name": "Branch Office - Network Room",
  "location": 15,
  "location_short_name": "branch-01-netroom",
  "latitude": "40.7128",
  "longitude": "-74.0060",
  "username": "device_agent_001",
  "update_frequency": 300,
  "address": "192.168.1.1",
  "last_connection": "2024-01-15T14:22:00Z",
  "last_configuration": "2024-01-15T09:15:00Z",
  "last_change": "2024-01-15T09:15:00Z",
  "created": "2024-01-10T16:45:00Z",
  "debug": false,
  "reboot": false,
  "factory": false,
  "device_factory": false,
  "sync": false,
  "reconf": false,
  "pending_settings": "firmware_upgrade, location_update"
}

Response Codes:

Status	Description
200	Success - Returns device details
401	Unauthorized - Invalid or missing API token
404	Not Found - Device with specified serial number does not exist
403	Forbidden - Insufficient permissions to access this device

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 used for comprehensive device reconfiguration or when synchronizing device data from external systems.

Use Cases:

Complete device reconfiguration during network changes
Synchronizing device data from external inventory systems
Bulk updates when device profiles or locations change
Correcting multiple device fields after discovery updates

Full URL Example:

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

Parameters:

Parameter	Type	In	Required	Description
serial_number	string	path	Yes	The serial number of the device to update
data	object	body	Yes	Complete device object with all fields to update

Request Body Example:

{
  "name": "Router-Branch-Office-01-Updated",
  "customer_id": "CUST-001-RTR-NEW",
  "is_active": true,
  "type": 6,
  "description": "Updated main router with enhanced security features",
  "organization_id": 123,
  "firmware_image": 45,
  "firmware_image_is_pending": true,
  "location_name": "Branch Office - Updated Network Room",
  "location": 16,
  "latitude": "40.7130",
  "longitude": "-74.0062",
  "username": "updated_device_agent_001",
  "password": "NewSecurePassword456!",
  "update_frequency": 180,
  "debug": true,
  "reboot": true
}

cURL Example:

curl -X PUT "https://control.zequenze.com/api/v1/inventory_device_serial/FCZ1234567890/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Router-Branch-Office-01-Updated",
    "is_active": true,
    "type": 6,
    "description": "Updated main router with enhanced security features",
    "organization_id": 123,
    "firmware_image": 45,
    "firmware_image_is_pending": true,
    "location": 16,
    "update_frequency": 180,
    "reboot": true
  }'

Example Response:

{
  "id": 1001,
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Router-Branch-Office-01-Updated",
  "customer_id": "CUST-001-RTR-NEW",
  "is_active": true,
  "status": "Up",
  "type": 6,
  "type_short_name": "enhanced-enterprise-router",
  "serial_number": "FCZ1234567890",
  "description": "Updated main router with enhanced security features",
  "organization_id": 123,
  "firmware_image": 45,
  "firmware_image_is_pending": true,
  "location": 16,
  "location_short_name": "branch-01-updated-netroom",
  "latitude": "40.7130",
  "longitude": "-74.0062",
  "username": "updated_device_agent_001",
  "update_frequency": 180,
  "last_change": "2024-01-15T16:45:00Z",
  "debug": true,
  "reboot": true,
  "pending_settings": "firmware_upgrade, reboot_scheduled"
}

Response Codes:

Status	Description
200	Success - Device successfully updated
400	Bad Request - Invalid data or validation errors
401	Unauthorized - Invalid or missing API token
404	Not Found - Device with specified serial number does not exist
403	Forbidden - Insufficient permissions to update this device

PATCH /inventory_device_serial/{serial_number}/

Description: Performs a partial update of a device record, modifying only the specified fields while leaving others unchanged. This endpoint is ideal for targeted updates like changing device status, triggering operations, or updating specific configuration parameters.

Use Cases:

Triggering device operations (reboot, factory reset, sync)
Updating device location during relocations
Changing firmware settings for scheduled upgrades
Enabling debug mode for troubleshooting
Updating device credentials or configuration

Full URL Example:

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

Parameters:

Parameter	Type	In	Required	Description
serial_number	string	path	Yes	The serial number of the device to update
data	object	body	Yes	Object containing only the fields to update

Request Body Examples:

Trigger a device reboot:

{
  "reboot": true,
  "debug": true
}

Update location and firmware:

{
  "location": 20,
  "location_name": "New Data Center - Rack 15",
  "firmware_image": 47,
  "firmware_image_is_pending": true
}

Synchronize device configuration:

{
  "sync": true,
  "reconf": true
}

cURL Example:

curl -X PATCH "https://control.zequenze.com/api/v1/inventory_device_serial/FCZ1234567890/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "location": 20,
    "location_name": "New Data Center - Rack 15",
    "firmware_image": 47,
    "firmware_image_is_pending": true
  }'

Example Response:

{
  "id": 1001,
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Router-Branch-Office-01",
  "customer_id": "CUST-001-RTR",
  "is_active": true,
  "status": "Up",
  "serial_number": "FCZ1234567890",
  "description": "Main router for branch office network infrastructure",
  "organization_id": 123,
  "firmware_image": 47,
  "firmware_image_is_pending": true,
  "location_name": "New Data Center - Rack 15",
  "location": 20,
  "location_short_name": "datacenter-rack-15",
  "last_change": "2024-01-15T17:20:00Z",
  "pending_settings": "location_update, firmware_upgrade"
}

Response Codes:

Status	Description
200	Success - Device partially updated
400	Bad Request - Invalid data or validation errors
401	Unauthorized - Invalid or missing API token
404	Not Found - Device with specified serial number does not exist
403	Forbidden - Insufficient permissions to update this device

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, replaced, or no longer part of your managed infrastructure.

Use Cases:

Decommissioning old equipment during hardware refreshes
Removing devices that have been permanently offline
Cleaning up inventory after equipment theft or loss
Bulk cleanup operations for retired network segments

Full URL Example:

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

Parameters:

Parameter	Type	In	Required	Description
serial_number	string	path	Yes	The serial number of the device to delete

cURL Example:

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

Response Codes:

Status	Description
204	No Content - Device successfully deleted
401	Unauthorized - Invalid or missing API token
404	Not Found - Device with specified serial number does not exist
403	Forbidden - Insufficient permissions to delete this device
409	Conflict - Device cannot be deleted due to dependencies

Common Use Cases

Use Case 1: Device Health Monitoring Dashboard

Build a real-time dashboard showing device status across your organization. Use GET /inventory_device_serial/ with status and organization filters, combined with update_status=true to get current device health. Implement pagination for large device fleets and use last_status_change_from to identify recently changed devices.

Use Case 2: Automated Device Provisioning

Implement zero-touch device provisioning by using POST /inventory_device_serial/ to pre-register devices with their serial numbers, location, and configuration templates. Once devices come online, use PATCH operations to trigger initial configuration sync and firmware updates.

Use Case 3: Remote Device Maintenance

Perform maintenance operations across your device fleet using targeted PATCH requests. Set reboot: true for device restarts, sync: true for configuration synchronization, or firmware_image_is_pending: true with a specific firmware_image for scheduled upgrades.

Use Case 4: Asset Tracking and Location Management

Track device movements and locations by updating location, latitude, and longitude fields using PATCH operations. Use the location filtering in GET requests to generate location-based reports and verify device placement.

Use Case 5: Bulk Device Operations

Process large device inventories efficiently using the filtering capabilities of the list endpoint combined with bulk update operations. Filter by type or organization to identify device groups, then use individual PATCH requests to apply configuration changes or operational commands.

Best Practices

Pagination Strategy: Always use limit and offset parameters when dealing with large device inventories. Start with reasonable page sizes (50-100 devices) and implement proper pagination logic to avoid timeouts and memory issues.

Status Updates: Use the update_status=true parameter judiciously, as it may increase response times but ensures you get real-time device status. For dashboards, consider caching strategies and only refresh status when needed.

Error Handling: Implement robust error handling for device operations. Many operations (reboot, firmware updates) are asynchronous - use the pending_settings field to track operation status and implement polling or webhook strategies for completion notifications.

Security Considerations:

Never log or expose device passwords in your applications
Use HTTPS for all API calls to protect authentication tokens
Implement proper token rotation and storage practices
Consider rate limiting your API calls to avoid overwhelming the system

Performance Optimization:

Use specific filters rather than retrieving all devices and filtering locally
Implement proper caching for device type and location reference data
Batch operations where possible rather than making individual API calls
Use partial updates (PATCH) instead of full updates (PUT) when changing few fields

Operational Safety:

Always verify device serial numbers before performing destructive operations
Implement confirmation workflows for operations like factory resets or device deletion
Use the debug: true flag during troubleshooting, but remember to disable it afterward
Monitor the pending_settings field to track ongoing operations and avoid conflicts