Skip to main content

Inventory Device Serial Operation

The Inventory Device Serial Operation API provides functionality to update device information using serial numbers as identifiers. This endpoint is designed for bulk device management operations where you need to modify device attributes or settings directly by serial number, making it ideal for inventory management systems and device provisioning workflows.

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 Operation API category contains endpoints specifically designed for device management operations that target devices by their unique serial numbers. This approach is particularly useful when integrating with external systems that primarily identify devices by serial numbers rather than internal database IDs.

This API is commonly used in scenarios where:

  • External inventory management systems need to sync device data
  • Bulk device configuration updates are required
  • Device provisioning workflows need to update device status or attributes
  • Asset management systems need to modify device properties

The serial number-based approach eliminates the need to first query for device IDs, streamlining operations where serial numbers are the primary identifier. This is especially valuable in enterprise environments where serial numbers are used for device tracking and management.

Endpoints

PUT /inventory_device_serial_operation/{serial_number}/

Description: Updates device information and configuration for a specific device identified by its serial number. This endpoint allows you to modify device attributes, status, configuration settings, and other properties without needing to know the internal device ID. It's designed for bulk operations and integration with external systems that use serial numbers as primary identifiers.

Use Cases:

  • Updating device status during deployment or decommissioning processes
  • Modifying device configuration settings during provisioning
  • Syncing device information from external asset management systems
  • Bulk updating device attributes during inventory reconciliation
  • Setting device location, assignment, or organizational unit information

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_serial_operation/ABC123456789/

Parameters:

Parameter Type In Required Description
serial_number string path Yes The unique serial number of the device to update
data string body Yes JSON string containing the device properties to update

cURL Example:

curl -X PUT "https://control.zequenze.com/api/v1/inventory_device_serial_operation/ABC123456789/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Conference Room Laptop",
    "status": "active",
    "location": "Building A - Room 101",
    "assigned_user": "john.doe@company.com",
    "organization_unit": "IT Department",
    "configuration": {
      "auto_update": true,
      "backup_enabled": true,
      "encryption_status": "enabled"
    },
    "tags": ["laptop", "conference-room", "windows"]
  }'

Example Request Body:

{
  "name": "Conference Room Laptop",
  "status": "active",
  "location": "Building A - Room 101",
  "assigned_user": "john.doe@company.com",
  "organization_unit": "IT Department",
  "device_type": "laptop",
  "manufacturer": "Dell",
  "model": "Latitude 5520",
  "configuration": {
    "auto_update": true,
    "backup_enabled": true,
    "encryption_status": "enabled",
    "compliance_profile": "corporate-standard"
  },
  "custom_fields": {
    "purchase_date": "2024-01-15",
    "warranty_expiry": "2027-01-15",
    "cost_center": "IT-001"
  },
  "tags": ["laptop", "conference-room", "windows"]
}

Example Response:

{
  "id": 1247,
  "serial_number": "ABC123456789",
  "name": "Conference Room Laptop",
  "status": "active",
  "location": "Building A - Room 101",
  "assigned_user": "john.doe@company.com",
  "organization_unit": "IT Department",
  "device_type": "laptop",
  "manufacturer": "Dell",
  "model": "Latitude 5520",
  "configuration": {
    "auto_update": true,
    "backup_enabled": true,
    "encryption_status": "enabled",
    "compliance_profile": "corporate-standard"
  },
  "custom_fields": {
    "purchase_date": "2024-01-15",
    "warranty_expiry": "2027-01-15",
    "cost_center": "IT-001"
  },
  "tags": ["laptop", "conference-room", "windows"],
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-03-15T14:22:33Z",
  "last_seen": "2024-03-15T14:20:15Z"
}

Response Codes:

Status Description
200 Success - Device updated successfully with the new information
400 Bad Request - Invalid data format or missing required fields
401 Unauthorized - Invalid or missing API token
404 Not Found - Device with the specified serial number does not exist
422 Unprocessable Entity - Valid JSON but invalid data values
500 Internal Server Error - Server-side error during processing

Common Use Cases

Use Case 1: Device Deployment Automation

When deploying devices to end users, update device status, assigned user, and location information using the device's serial number. This is typically integrated into device provisioning workflows where the serial number is scanned or entered during the deployment process.

Use Case 2: Asset Management Integration

Sync device information from external asset management systems that use serial numbers as primary identifiers. Update device location, cost center, warranty information, and other asset-related properties without needing to map to internal IDs.

Use Case 3: Bulk Configuration Updates

Apply configuration changes to multiple devices by serial number during compliance updates or security policy changes. This allows for batch processing where each device is identified by its unique serial number.

Use Case 4: Inventory Reconciliation

Update device information during physical inventory audits where devices are identified by their serial numbers. Correct location information, update status, and modify other attributes based on physical verification.

Use Case 5: Device Lifecycle Management

Update device status and configuration during different lifecycle phases (deployment, active use, maintenance, decommissioning) using the serial number as the consistent identifier throughout the device's lifecycle.

Best Practices

  • Validate Serial Numbers: Always ensure serial numbers are properly formatted and exist in the system before making update requests to avoid 404 errors.

  • Use Partial Updates: Only include fields that need to be updated in the request body. The API supports partial updates, so you don't need to send the entire device object.

  • Batch Operations: When updating multiple devices, implement proper rate limiting and consider processing devices in batches to avoid overwhelming the API.

  • Error Handling: Implement robust error handling for common scenarios like device not found (404) or invalid data (400/422). Log failed operations for troubleshooting and retry mechanisms.

  • Data Validation: Validate device data on the client side before sending requests, especially for fields like email addresses, dates, and enumerated values like status.

  • Idempotent Operations: Design your integration to be idempotent - the same update operation should be safe to retry without causing unintended side effects.

  • Audit Trail: Keep track of what changes are being made for compliance and troubleshooting purposes, as this endpoint modifies device records directly.

  • Security: Never log or expose API tokens in your application code or logs. Use secure credential storage and rotation practices.

Back to top