Skip to main content
POST
/
v1
/
devices
/
register
curl -X POST https://api.bookovia.com/v1/devices/register \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": "OBD_12345_ABC789",
    "device_type": "obd_ii",
    "device_name": "Fleet Vehicle #247",
    "vehicle_id": "vehicle_67890",
    "manufacturer": "Geotab",
    "model": "GO9",
    "firmware_version": "8.4.2.1",
    "imei": "357240051111110",
    "network_provider": "Verizon",
    "registration_metadata": {
      "installation_date": "2024-03-15T09:30:00Z",
      "installer_id": "tech_001",
      "location": "Fleet Depot 1"
    }
  }'
{
  "device_id": "OBD_12345_ABC789",
  "status": "registered",
  "registration_token": "reg_token_abc123xyz789",
  "activation_url": "https://api.bookovia.com/v1/devices/activate/reg_token_abc123xyz789",
  "expires_at": "2024-03-22T09:30:00Z",
  "message": "Device successfully registered. Complete activation within 7 days.",
  "device_info": {
    "device_name": "Fleet Vehicle #247",
    "device_type": "obd_ii",
    "manufacturer": "Geotab",
    "model": "GO9",
    "firmware_version": "8.4.2.1",
    "network_provider": "Verizon"
  },
  "vehicle_assignment": {
    "vehicle_id": "vehicle_67890",
    "assigned_at": "2024-03-15T09:30:00Z"
  },
  "next_steps": {
    "activate_device": "Send GET request to activation_url",
    "firmware_update": "Check for latest firmware at /devices/{device_id}/firmware",
    "configuration": "Configure device settings at /devices/{device_id}/settings"
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.bookovia.com/llms.txt

Use this file to discover all available pages before exploring further.

Authentication

This endpoint requires an API key. Include your API key in the X-API-Key header.

Request

curl -X POST https://api.bookovia.com/v1/devices/register \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": "OBD_12345_ABC789",
    "device_type": "obd_ii",
    "device_name": "Fleet Vehicle #247",
    "vehicle_id": "vehicle_67890",
    "manufacturer": "Geotab",
    "model": "GO9",
    "firmware_version": "8.4.2.1",
    "imei": "357240051111110",
    "network_provider": "Verizon",
    "registration_metadata": {
      "installation_date": "2024-03-15T09:30:00Z",
      "installer_id": "tech_001",
      "location": "Fleet Depot 1"
    }
  }'

Response

{
  "device_id": "OBD_12345_ABC789",
  "status": "registered",
  "registration_token": "reg_token_abc123xyz789",
  "activation_url": "https://api.bookovia.com/v1/devices/activate/reg_token_abc123xyz789",
  "expires_at": "2024-03-22T09:30:00Z",
  "message": "Device successfully registered. Complete activation within 7 days.",
  "device_info": {
    "device_name": "Fleet Vehicle #247",
    "device_type": "obd_ii",
    "manufacturer": "Geotab",
    "model": "GO9",
    "firmware_version": "8.4.2.1",
    "network_provider": "Verizon"
  },
  "vehicle_assignment": {
    "vehicle_id": "vehicle_67890",
    "assigned_at": "2024-03-15T09:30:00Z"
  },
  "next_steps": {
    "activate_device": "Send GET request to activation_url",
    "firmware_update": "Check for latest firmware at /devices/{device_id}/firmware",
    "configuration": "Configure device settings at /devices/{device_id}/settings"
  }
}

Request Parameters

ParameterTypeRequiredDescription
device_idstringYesUnique identifier for the device
device_typestringYesType of device: obd_ii, mobile, dashcam, sensor_hub
device_namestringYesHuman-readable name for the device
vehicle_idstringYesID of the vehicle this device will be assigned to
manufacturerstringYesDevice manufacturer name
modelstringYesDevice model number
firmware_versionstringYesCurrent firmware version
imeistringYesDevice IMEI number (15 digits)
network_providerstringYesCellular network provider
registration_metadataobjectNoAdditional metadata about the installation

Use Cases

Fleet Management Device Registration

Register OBD-II devices for comprehensive fleet monitoring and telematics data collection:
// Register multiple fleet vehicles with OBD-II devices
const fleetDevices = [
  {
    device_id: 'OBD_FLEET_001',
    device_type: 'obd_ii',
    device_name: 'Delivery Truck #1',
    vehicle_id: 'truck_001',
    manufacturer: 'Geotab',
    model: 'GO9'
  },
  {
    device_id: 'OBD_FLEET_002', 
    device_type: 'obd_ii',
    device_name: 'Service Van #12',
    vehicle_id: 'van_012',
    manufacturer: 'Verizon Connect',
    model: 'Reveal'
  }
];

for (const device of fleetDevices) {
  const registration = await registerDevice({
    ...device,
    firmware_version: '8.4.2.1',
    imei: generateIMEI(),
    network_provider: 'Verizon',
    registration_metadata: {
      installation_date: new Date().toISOString(),
      installer_id: 'fleet_tech_001',
      location: 'Central Fleet Depot',
      installation_type: 'professional'
    }
  });
  
  console.log(`Registered: ${registration.device_id}`);
}

Mobile Device Registration

Register mobile devices for driver-facing applications and location tracking:
# Register driver mobile devices for telematics data collection
def register_driver_mobile(driver_id, vehicle_id, device_info):
    registration_data = {
        "device_id": f"MOBILE_{driver_id}_{device_info['imei']}",
        "device_type": "mobile",
        "device_name": f"Driver Phone - {driver_id}",
        "vehicle_id": vehicle_id,
        "manufacturer": device_info['manufacturer'],
        "model": device_info['model'],
        "firmware_version": device_info['os_version'],
        "imei": device_info['imei'],
        "network_provider": device_info['carrier'],
        "registration_metadata": {
            "driver_id": driver_id,
            "app_version": "2.1.4",
            "permissions_granted": ["location", "camera", "microphone"],
            "registration_type": "driver_self_service"
        }
    }
    
    response = requests.post(
        "https://api.bookovia.com/v1/devices/register",
        headers={"X-API-Key": "your_api_key_here"},
        json=registration_data
    )
    
    return response.json()

# Register driver's mobile device
driver_registration = register_driver_mobile(
    driver_id="driver_12345",
    vehicle_id="car_789",
    device_info={
        "manufacturer": "Apple",
        "model": "iPhone 14 Pro",
        "os_version": "17.2.1",
        "imei": "357240051111110",
        "carrier": "T-Mobile"
    }
)

IoT Sensor Hub Registration

Register IoT sensor hubs for comprehensive vehicle monitoring and predictive maintenance:
// Register IoT sensor hub with multiple sensors
type SensorHubRegistration struct {
    DeviceID       string                 `json:"device_id"`
    DeviceType     string                 `json:"device_type"`
    DeviceName     string                 `json:"device_name"`
    VehicleID      string                 `json:"vehicle_id"`
    Manufacturer   string                 `json:"manufacturer"`
    Model          string                 `json:"model"`
    FirmwareVer    string                 `json:"firmware_version"`
    IMEI           string                 `json:"imei"`
    NetworkProvider string                `json:"network_provider"`
    Metadata       SensorHubMetadata      `json:"registration_metadata"`
}

type SensorHubMetadata struct {
    SensorTypes      []string           `json:"sensor_types"`
    SamplingRate     int               `json:"sampling_rate_hz"`
    DataTransmission string            `json:"data_transmission"`
    PowerSource      string            `json:"power_source"`
    InstallationID   string            `json:"installation_id"`
}

func registerSensorHub(vehicleID string) (*DeviceRegistrationResponse, error) {
    registration := SensorHubRegistration{
        DeviceID:       fmt.Sprintf("SENSOR_HUB_%s", vehicleID),
        DeviceType:     "sensor_hub",
        DeviceName:     fmt.Sprintf("IoT Sensors - Vehicle %s", vehicleID),
        VehicleID:      vehicleID,
        Manufacturer:   "Bookovia",
        Model:          "SH-2000",
        FirmwareVer:    "3.1.2",
        IMEI:           generateIMEI(),
        NetworkProvider: "AT&T",
        Metadata: SensorHubMetadata{
            SensorTypes: []string{
                "accelerometer", "gyroscope", "gps", "obd_ii",
                "temperature", "humidity", "pressure", "camera"
            },
            SamplingRate:     100,
            DataTransmission: "cellular_primary_wifi_backup",
            PowerSource:      "vehicle_battery_with_backup",
            InstallationID:   "INST_" + generateInstallID(),
        },
    }
    
    // Register the sensor hub
    response := registerDevice(registration)
    return response, nil
}

Dashcam Device Registration

Register dashcam devices for safety monitoring and incident analysis:
interface DashcamRegistration {
  device_id: string;
  device_type: 'dashcam';
  device_name: string;
  vehicle_id: string;
  manufacturer: string;
  model: string;
  firmware_version: string;
  imei: string;
  network_provider: string;
  registration_metadata: {
    camera_specs: {
      resolution: string;
      frame_rate: number;
      night_vision: boolean;
      field_of_view: number;
    };
    storage_specs: {
      capacity_gb: number;
      recording_duration_hours: number;
      cloud_backup: boolean;
    };
    ai_features: string[];
    installation_location: string;
  };
}

async function registerFleetDashcams(vehicleIds: string[]): Promise<void> {
  const registrations = vehicleIds.map(vehicleId => ({
    device_id: `DASHCAM_${vehicleId}`,
    device_type: 'dashcam' as const,
    device_name: `Safety Camera - Vehicle ${vehicleId}`,
    vehicle_id: vehicleId,
    manufacturer: 'Lytx',
    model: 'DriveCam SF300',
    firmware_version: '5.2.1',
    imei: generateIMEI(),
    network_provider: 'Verizon',
    registration_metadata: {
      camera_specs: {
        resolution: '1080p_dual_facing',
        frame_rate: 30,
        night_vision: true,
        field_of_view: 170
      },
      storage_specs: {
        capacity_gb: 64,
        recording_duration_hours: 48,
        cloud_backup: true
      },
      ai_features: [
        'collision_detection',
        'lane_departure_warning', 
        'distracted_driving_detection',
        'speeding_detection',
        'harsh_event_detection'
      ],
      installation_location: 'windshield_center_mount'
    }
  }));

  // Register all dashcams in parallel
  const results = await Promise.all(
    registrations.map(reg => registerDevice(reg))
  );

  console.log(`Registered ${results.length} dashcam devices`);
}

Best Practices

Security & Authentication

  • Store device registration tokens securely and never expose them in client-side code
  • Implement device certificate-based authentication for production deployments
  • Use IMEI validation to prevent registration of invalid or blacklisted devices
  • Rotate registration tokens regularly and implement token expiration monitoring

Device Lifecycle Management

  • Implement automated device activation workflows after registration
  • Set up monitoring for device registration status and activation completion
  • Configure alerts for failed device registrations and activation timeouts
  • Plan for device deregistration and data migration procedures

Fleet Scale Registration

  • Use batch registration APIs for large fleet deployments
  • Implement registration progress tracking and error handling
  • Set up device inventory management with registration status tracking
  • Configure automated device provisioning workflows

Data Privacy & Compliance

  • Ensure device registration complies with regional data protection regulations
  • Implement consent management for driver privacy and data collection
  • Configure data retention policies for device registration metadata
  • Set up audit logging for all device registration activities