Automatic Device Creation

When integrating external systems with Spot AI, you can automatically create and manage devices based on event data. This guide explains how to use External Device IDs and Device ID Templates to streamline device management.

Overview

Spot Connect supports two methods for associating events with devices:

1. Manual Device Mapping: Create devices in the Spot dashboard and reference them by integration_device_id in your events
2. Automatic Device Creation: Let Spot automatically create devices based on identifiers in your event data

Automatic device creation is useful when:

• Your external system has its own device identifiers (register IDs, terminal IDs, etc.)
• You want devices to be created on-demand as events arrive
• You need to sync device inventory from an external system

External Device ID

The device_external_id field allows you to reference devices by a vendor-provided identifier instead of Spot's internal device ID.

How It Works

When you send an event with device_external_id:

1. Spot looks for an existing device with that external ID within your integration
2. If found, the event is associated with that device
3. If not found, a new device is automatically created with that external ID

Example Request

{
  "integration_event_type_id": 123,
  "device_external_id": "REGISTER-001",
  "timestamp": "2024-01-15T10:30:00Z",
  "attributes": {
    "transaction_id": "TXN-456",
    "amount": 99.99
  }
}

Precedence Rules

When multiple device identifiers are provided:

1. integration_device_id always takes precedence (no validation is performed)
2. If integration_device_id is not provided, device_external_id is used
3. If neither is provided, the Device ID Template is evaluated (if configured)

Note: If you provide an invalid integration_device_id, the request will fail. The system does not fall back to device_external_id.

Device ID Templates

Device ID Templates solve a common integration challenge: your external system doesn't provide a single unique device identifier. Instead, you may need to construct one from multiple fields.

For example, a POS system might send events with separate store_id and lane_id fields, but no combined terminal identifier. A template like {store_id}:{lane_id} constructs a unique device ID from these fields.

Configuring Templates

Templates are configured on Integration Event Types using the external_device_id_template field. You can set this when creating or updating an event type via the API:

# Create event type with template
POST /v1/integrations/{integration_id}/event-types
{
  "name": "POS Transaction",
  "schema": { ... },
  "external_device_id_template": "{store_id}:{lane_id}"
}

# Update existing event type to add template
PUT /v1/integrations/{integration_id}/event-types/{event_type_id}
{
  "external_device_id_template": "{store_id}:{lane_id}"
}

Template Syntax

Templates use {variable} syntax to reference fields from the event attributes:

Note: Event type schemas support up to 2 levels of nesting: top-level objects with primitive properties, or arrays of objects with primitive properties. Deeper nesting (e.g., {a.b.c.d}) is not supported.

Example Configuration

Event Type Configuration:

{
  "name": "POS Transaction",
  "external_device_id_template": "{store_id}:{lane_id}"
}

Incoming Event:

{
  "integration_event_type_id": 123,
  "timestamp": "2024-01-15T10:30:00Z",
  "attributes": {
    "transaction_id": "TXN-456",
    "store_id": "STORE-100",
    "lane_id": "3"
  }
}

Result: The template {store_id}:{lane_id} produces "STORE-100:3" which is used as the external device ID.

Template Requirements

• The template must reference fields that exist in your event type's schema
• All referenced fields must be marked as required in the schema
• Templates are validated when creating or updating an event type
• Any value type (string, number, boolean) can be used and will be converted to a string

Precedence with Templates

The complete device resolution order is:

1. integration_device_id — if provided, used directly (highest precedence)
2. device_external_id — if provided, looks up or creates device
3. Device ID Template — if configured, evaluates template against event attributes
4. Error — if none of the above resolve a device, the request fails

Note: There is no fallback between these options. If template evaluation fails (e.g., missing required field), the entire request fails.

Best Practices

Choosing Between Methods

Naming Conventions

• Use consistent, meaningful external IDs (e.g., REGISTER-001, STORE-100:LANE-3)
• External IDs are case-sensitive
• External IDs must be unique within an integration

Error Handling

Device resolution errors will cause the entire request to fail:

• Missing device identifier: If no integration_device_id, device_external_id, or template is available, the request returns 400 Bad Request
• Template evaluation failure: If a template references a missing field, the request fails with an error indicating the missing placeholder
• Invalid device ID: If integration_device_id references a non-existent device, the request fails

Events are only ingested after successful device resolution.

API Reference

For complete API documentation, see:

• Ingest Integration Event - Event ingestion with device options
• Create Integration Event Type - Configure device ID templates