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:

Manual Device Mapping: Create devices in the Spot dashboard and reference them by integration_device_id in your events
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:

Spot looks for an existing device with that external ID within your integration
If found, the event is associated with that device
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:

integration_device_id always takes precedence (no validation is performed)
If integration_device_id is not provided, device_external_id is used
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:

Syntax	Description	Example
`{field}`	Top-level field	`{register_id}`
`{field}:{field}`	Multiple fields	`{store_id}:{lane_id}`
`{object.field}`	Nested object field	`{address.store_id}`
`{array.index.field}`	Array element field	`{locations.0.id}`

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:

integration_device_id — if provided, used directly (highest precedence)
device_external_id — if provided, looks up or creates device
Device ID Template — if configured, evaluates template against event attributes
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

Scenario	Recommended Approach
Known, static device set	Manual device creation with `integration_device_id`
External system provides unique device ID	`device_external_id`
Need to construct ID from multiple fields	Device ID Template
Multiple event types, same device ID location	Configure template per event type

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