API Reference

Devices API

Register and manage security devices including cameras and bridges

Overview

The Devices API allows you to register, update, retrieve, and delete security devices at customer sites. Devices include cameras, bridges, and other security hardware.

Bulk Operations

The Devices API supports bulk creation, update, and deletion operations for efficient device management.

Device Types

  • camera: Video surveillance camera
  • bridge: Communication bridge for alarm panels

Endpoints

Create Devices (Bulk)

Register multiple devices at once for a site.

Endpoint: POST /partner/v1/dealers/{dealerId}/sites/{siteId}/devices

Authentication: OAuth 2.0 Client Credentials Grant

Request

Path Parameters:

  • dealerId (number, required): The dealer ID from CHeKT (example: 2)
  • siteId (number, required): The site ID from CHeKT (example: 3)

Headers:

  • Authorization: Bearer {access_token}
  • x-partner-trace-id (optional): UUID for request tracking

Body (Array):

[
  {
    "external_device_id": "adc-67890",
    "device_type": "camera",
    "name": "Front Door Camera",
    "zone_number": "001",
    "additional_zone_numbers": "002,003",
    "mac": "1234567890",
    "manufacturer": "CHeKT",
    "model": "ADC2345",
    "serial_number": "SN1234567890"
  }
]

Parameters:

  • external_device_id (string, required): Unique identifier from your system
  • device_type (string, required): Device type (camera or bridge)
  • zone_number (string, required): Zone number of the device
  • additional_zone_numbers (string, optional): Comma-separated additional zone numbers
  • name (string, optional): Device name or label
  • mac (string, optional): MAC address
  • manufacturer (string, optional): Device manufacturer
  • model (string, optional): Device model number
  • serial_number (string, optional): Device serial number

Response (201 Created)

{
  "success_count": 1,
  "failure_count": 0,
  "results": [
    {
      "is_successful": true,
      "req": {
        "external_device_id": "adc-67890",
        "device_type": "camera",
        "zone_number": "001"
      },
      "res": {
        "device_id": 1,
        "device_type": "camera",
        "zone_number": "001",
        "additional_zone_numbers": "002,003",
        "manufacturer": "CHeKT",
        "registered_by_partner": "adc",
        "external_device_id": "adc-67890",
        "name": "Front Door Camera",
        "mac": "1234567890",
        "model": "ADC2345",
        "serial_number": "SN1234567890",
        "created_at": "2021-07-01T00:00:00.000Z",
        "updated_at": "2021-07-01T00:00:00.000Z"
      }
    }
  ]
}

Response Fields:

  • success_count (number): Number of successfully created devices
  • failure_count (number): Number of failed device creations
  • results (array): Detailed results for each device
    • is_successful (boolean): Whether creation succeeded
    • status_code (number): HTTP status code (present only if failed)
    • error_message (string): Error details (present only if failed)
    • req (object): Original request data
    • res (object): Created device details (present only if successful)

List All Devices

Retrieve all devices for a specific site.

Endpoint: GET /partner/v1/dealers/{dealerId}/sites/{siteId}/devices

Authentication: OAuth 2.0 Client Credentials Grant

Request

Path Parameters:

  • dealerId (number, required): The dealer ID from CHeKT
  • siteId (number, required): The site ID from CHeKT

Headers:

  • Authorization: Bearer {access_token}
  • x-partner-trace-id (optional): UUID for request tracking

Response (200 OK)

[
  {
    "device_id": 1,
    "device_type": "camera",
    "zone_number": "001",
    "additional_zone_numbers": "002,003",
    "manufacturer": "CHeKT",
    "registered_by_partner": "adc",
    "external_device_id": "adc-67890",
    "name": "Front Door Camera",
    "mac": "1234567890",
    "model": "ADC2345",
    "serial_number": "SN1234567890",
    "created_at": "2021-07-01T00:00:00.000Z",
    "updated_at": "2021-07-01T00:00:00.000Z"
  }
]

Get a Specific Device

Retrieve detailed information about a single device.

Endpoint: GET /partner/v1/dealers/{dealerId}/sites/{siteId}/devices/{deviceId}

Authentication: OAuth 2.0 Client Credentials Grant

Request

Path Parameters:

  • dealerId (number, required): The dealer ID from CHeKT
  • siteId (number, required): The site ID from CHeKT
  • deviceId (number, optional): The device ID from CHeKT (example: 3)

Headers:

  • Authorization: Bearer {access_token}
  • x-partner-trace-id (optional): UUID for request tracking

Response (200 OK)

{
  "device_id": 1,
  "device_type": "camera",
  "zone_number": "001",
  "additional_zone_numbers": "002,003",
  "manufacturer": "CHeKT",
  "registered_by_partner": "adc",
  "external_device_id": "adc-67890",
  "name": "Front Door Camera",
  "mac": "1234567890",
  "model": "ADC2345",
  "serial_number": "SN1234567890",
  "created_at": "2021-07-01T00:00:00.000Z",
  "updated_at": "2021-07-01T00:00:00.000Z"
}

Response Fields:

  • device_id (number): Unique identifier assigned by CHeKT
  • device_type (string): Device type (camera or bridge)
  • zone_number (string): Zone number
  • additional_zone_numbers (string): Comma-separated additional zone numbers
  • manufacturer (string): Device manufacturer
  • registered_by_partner (string): Partner who registered the device (adc, chekt, oe)
  • external_device_id (string): Your system's identifier
  • name (string): Device name
  • mac (string): MAC address
  • model (string): Device model
  • serial_number (string): Serial number
  • created_at (string): Creation timestamp
  • updated_at (string): Last update timestamp

Update Devices (Bulk)

Update multiple devices at once.

Endpoint: PUT /partner/v1/dealers/{dealerId}/sites/{siteId}/devices

Authentication: OAuth 2.0 Client Credentials Grant

Request

Path Parameters:

  • dealerId (number, required): The dealer ID from CHeKT
  • siteId (number, required): The site ID from CHeKT

Headers:

  • Authorization: Bearer {access_token}
  • x-partner-trace-id (optional): UUID for request tracking

Body (Array):

[
  {
    "device_id": 123,
    "name": "Updated Front Door Camera",
    "zone_number": "005",
    "additional_zone_numbers": "006,007",
    "mac": "0987654321",
    "manufacturer": "Updated Manufacturer",
    "model": "NEW-MODEL-2024",
    "serial_number": "NEW-SN-123"
  }
]

Parameters:

  • device_id (number, required): CHeKT device ID to update
  • name (string, optional): Updated device name
  • zone_number (string, optional): Updated zone number
  • additional_zone_numbers (string, optional): Updated additional zones
  • mac (string, optional): Updated MAC address
  • manufacturer (string, optional): Updated manufacturer
  • model (string, optional): Updated model
  • serial_number (string, optional): Updated serial number

Response (200 OK)

{
  "success_count": 1,
  "failure_count": 0,
  "results": [
    {
      "is_successful": true,
      "req": {
        "device_id": 123,
        "name": "Updated Front Door Camera"
      },
      "res": {
        "device_id": 123,
        "device_type": "camera",
        "zone_number": "005",
        "name": "Updated Front Door Camera",
        "updated_at": "2021-07-01T00:00:00.000Z"
      }
    }
  ]
}

Delete Devices (Bulk)

Delete multiple devices at once.

Endpoint: POST /partner/v1/dealers/{dealerId}/sites/{siteId}/devices/bulk-delete

Authentication: OAuth 2.0 Client Credentials Grant

Bulk deletion is permanent. Ensure devices are properly backed up or documented before deletion.

Request

Path Parameters:

  • dealerId (number, required): The dealer ID from CHeKT
  • siteId (number, required): The site ID from CHeKT

Headers:

  • Authorization: Bearer {access_token}
  • x-partner-trace-id (optional): UUID for request tracking

Body:

{
  "deviceIds": [123, 891]
}

Parameters:

  • deviceIds (array of numbers, required): List of device IDs to delete

Response (200 OK)

{
  "success_count": 2,
  "failure_count": 0,
  "results": [
    {
      "is_successful": true,
      "req": {
        "device_id": 123
      },
      "res": {
        "device_id": 123,
        "device_type": "camera",
        "zone_number": "001"
      }
    },
    {
      "is_successful": true,
      "req": {
        "device_id": 891
      },
      "res": {
        "device_id": 891,
        "device_type": "bridge",
        "zone_number": "002"
      }
    }
  ]
}

Error Responses

Status CodeDescriptionSolution
400Bad Request - Invalid input or parametersCheck your request payload format
401Unauthorized - Invalid or expired tokenRefresh your access token
403Forbidden - Access deniedVerify your permissions
404Not Found - Device, site, or dealer does not existCheck the IDs

Code Examples

cURL

# Create devices (bulk)
curl -X POST https://api.chekt.com/partner/v1/dealers/2/sites/3/devices \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-partner-trace-id: 550e8400-e29b-41d4-a716-123456789000" \
  -d '[
    {
      "external_device_id": "adc-67890",
      "device_type": "camera",
      "zone_number": "001",
      "name": "Front Door Camera"
    }
  ]'

# Get all devices
curl -X GET https://api.chekt.com/partner/v1/dealers/2/sites/3/devices \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-partner-trace-id: 550e8400-e29b-41d4-a716-123456789000"

# Bulk delete devices
curl -X POST https://api.chekt.com/partner/v1/dealers/2/sites/3/devices/bulk-delete \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-partner-trace-id: 550e8400-e29b-41d4-a716-123456789000" \
  -d '{
    "deviceIds": [123, 891]
  }'

JavaScript

// Create devices (bulk)
const response = await fetch("https://api.chekt.com/partner/v1/dealers/2/sites/3/devices", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${accessToken}`,
    "x-partner-trace-id": "550e8400-e29b-41d4-a716-123456789000"
  },
  body: JSON.stringify([
    {
      external_device_id: "adc-67890",
      device_type: "camera",
      zone_number: "001",
      name: "Front Door Camera"
    }
  ])
});

const result = await response.json();
console.log(`Created ${result.success_count} devices`);

Python

import requests

# Create devices (bulk)
response = requests.post(
    "https://api.chekt.com/partner/v1/dealers/2/sites/3/devices",
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {access_token}",
        "x-partner-trace-id": "550e8400-e29b-41d4-a716-123456789000"
    },
    json=[
        {
            "external_device_id": "adc-67890",
            "device_type": "camera",
            "zone_number": "001",
            "name": "Front Door Camera"
        }
    ]
)

result = response.json()
print(f"Created {result['success_count']} devices")

Best Practices

  • Validate device_type before submission (camera or bridge)
  • Ensure zone_number uniqueness within a site
  • Use bulk operations for efficient device management
  • Handle partial failures in bulk operations gracefully
  • Store device_id for future updates and monitoring
  • Document MAC addresses for network troubleshooting

Next Steps

Next Steps