Bulk import

Bulk import provisions a whole factory batch in one shot. You upload a CSV of hardware IDs and profile assignments; the platform validates each row, creates the provisioning records, and hands you back a one-time encrypted manifest of the generated keys to ship to the factory. Each device then comes online on its own via the key claim flow.

This is the path for hundreds or thousands of devices. For a single device, use manual registration.

The flow at a glance

1. Prepare a CSV of the batch — one row per device.
2. Upload it as a tenant admin. Each row is validated independently.
3. Review the result — created records, plus a per-row report of any failures and duplicates.
4. Download the encrypted manifest of generated provisioning keys (shown once).
5. Distribute the manifest to the factory; keys are burned into devices.
6. Devices claim themselves on first boot per the key claim flow.

CSV format

One row per device. The header row names the columns; order does not matter.

Column	Required	Description
hardware_id	yes	Stable hardware identifier; unique within the tenant
profile_id	yes	Device profile the device inherits
name	no	Human-readable device name
groups	no	Group names; separate multiple with ;
tags	no	key=value pairs; separate multiple with ;

hardware_id,profile_id,name,groups,tags
AA:BB:CC:00:11:01,p_temp_sensor_v2,Cold Store Sensor 001,cold-store;floor-1,region=eu;line=A
AA:BB:CC:00:11:02,p_temp_sensor_v2,Cold Store Sensor 002,cold-store;floor-1,region=eu;line=A
AA:BB:CC:00:11:03,p_temp_sensor_v2,Cold Store Sensor 003,cold-store;floor-2,region=eu;line=B
AA:BB:CC:00:11:04,p_humidity_v1,Humidity Probe 001,cold-store;floor-2,region=eu;line=B

Tip

Reference an existing device profile in profile_id and keep the CSV minimal. The profile carries tags, config, anchoring policy, telemetry schema, and the credentials policy, so you only need per-device overrides in the CSV.

Per-row validation and partial import

Every row is validated on its own. Validation checks include:

• hardware_id is present and well-formed
• profile_id references a profile that exists in your tenant
• hardware_id is not already taken in the tenant (duplicate detection)

With partial import enabled, valid rows are imported even if other rows fail — the import does not abort on the first bad row. The result reports outcomes per row so you can fix and re-upload only the failures:

{
  "imported": 498,
  "failed": 2,
  "rows": [
    { "row": 312, "hardware_id": "AA:BB:CC:00:12:38", "status": "duplicate", "reason": "hardware_id already exists in tenant" },
    { "row": 457, "hardware_id": "", "status": "invalid", "reason": "hardware_id is required" }
  ]
}

Note

Duplicate hardware IDs are reported per row, not treated as a hard failure of the whole batch. Re-uploading a CSV that overlaps a previous import will simply report the overlapping rows as duplicates and import the rest — safe to retry.

The provisioning-key manifest

On success the platform generates the provisioning keys for the batch and returns them as a one-time, encrypted manifest. Like every raw secret on CORE-M, the keys are shown once — only their SHA-256 hashes are stored.

Danger

The manifest is your only copy of the raw provisioning keys. Download and store it securely the moment the import completes. If you lose it, you cannot recover the keys — you must regenerate provisioning records and re-import. Treat the manifest as factory-floor secret material: encrypted in transit and at rest, access-controlled, and deleted once the keys are burned into devices.

Distribute the manifest to your factory or contract manufacturer over a secure channel. Each device gets its provisioning key flashed during manufacture.

Devices come online

Once a device boots in the field with its provisioning key, it claims its identity exactly as described in the key claim flow: it calls POST /api/v1/provision, the platform derives the tenant from the key, creates (or idempotently returns) the device, and issues its API key. From the device’s perspective, bulk import is invisible — it just claims and connects.

Related

Provisioning by key claim What each device does on first boot after a bulk import.

Device profiles The profile referenced by every CSV row, carrying the batch's shared defaults.

Device identity & credentials hardware_id uniqueness and the credentials devices receive on claim.