Skip to main content
POST
/
api
/
ext-v1
/
deviceAssignment
/
assignDeviceToOwners
curl -X POST https://admin.telemetron.ai/api/ext-v1/deviceAssignment/assignDeviceToOwners \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "deviceIdentifier": "SN-12345-ABCDE",
    "customerEmails": ["john.doe@example.com"]
  }'

{
  "success": true,
  "message": "Successfully assigned device to 2 customer(s)",
  "deviceId": "dev_a1b2c3d4e5f6",
  "deviceWasCreated": false,
  "assignedCustomers": [
    {
      "email": "john.doe@example.com",
      "customerId": "cust_111222333",
      "wasCreated": false
    },
    {
      "email": "jane.smith@example.com",
      "customerId": "cust_444555666",
      "wasCreated": true
    }
  ]
}

Documentation Index

Fetch the complete documentation index at: https://docs.telemetron.ai/llms.txt

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

​
Overview

Assigns a device to one or more customers. Creates the mapping for telemetry correlation. Features:
  • Auto-creates customers if they don’t exist
  • Supports multi-owner assignments (shared/family devices)
  • Optional auto-create for devices (requires deviceType)

​
Authentication

​
x-api-key
string
required
Your organization’s API key

​
Request Body

​
deviceIdentifier
string
required
The unique identifier for the device (e.g., serial number, MAC address)
​
customerEmails
array
required
Array of customer email addresses to assign the device to. Must contain at least one valid email.
​
autoCreateDevice
boolean
default:false
If true, creates the device automatically if it doesn’t exist in the system. Defaults to false.
​
deviceType
string
Required when autoCreateDevice is true. Specifies the device type (e.g., “Thermostat”, “Sensor”, “Gateway”). This field is mandatory for creating new devices.

​
Response

​
success
boolean
Indicates if the operation was successful
​
message
string
Description of the operation result
​
deviceId
string
The unique device ID in the Telemetron system
​
deviceWasCreated
boolean
Indicates whether the device was created during this operation. Always present in the response.
​
assignedCustomers
array
Array of customer objects that were assigned the device

​
Examples

​
Single Customer Assignment

curl -X POST https://admin.telemetron.ai/api/ext-v1/deviceAssignment/assignDeviceToOwners \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "deviceIdentifier": "SN-12345-ABCDE",
    "customerEmails": ["john.doe@example.com"]
  }'

​
Bulk Assignment (Multiple Customers)

curl -X POST https://admin.telemetron.ai/api/ext-v1/deviceAssignment/assignDeviceToOwners \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "deviceIdentifier": "SN-12345-ABCDE",
    "customerEmails": [
      "john.doe@example.com",
      "jane.smith@example.com"
    ]
  }'

​
Auto-Create Device

curl -X POST https://admin.telemetron.ai/api/ext-v1/deviceAssignment/assignDeviceToOwners \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "deviceIdentifier": "SN-67890-FGHIJ",
    "customerEmails": ["john.doe@example.com"],
    "autoCreateDevice": true,
    "deviceType": "Thermostat"
  }'

​
Response

{
  "success": true,
  "message": "Successfully assigned device to 2 customer(s)",
  "deviceId": "dev_a1b2c3d4e5f6",
  "deviceWasCreated": false,
  "assignedCustomers": [
    {
      "email": "john.doe@example.com",
      "customerId": "cust_111222333",
      "wasCreated": false
    },
    {
      "email": "jane.smith@example.com",
      "customerId": "cust_444555666",
      "wasCreated": true
    }
  ]
}

curl -X POST https://admin.telemetron.ai/api/ext-v1/deviceAssignment/assignDeviceToOwners \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "deviceIdentifier": "SN-12345-ABCDE",
    "customerEmails": ["john.doe@example.com"]
  }'

{
  "success": true,
  "message": "Successfully assigned device to 2 customer(s)",
  "deviceId": "dev_a1b2c3d4e5f6",
  "deviceWasCreated": false,
  "assignedCustomers": [
    {
      "email": "john.doe@example.com",
      "customerId": "cust_111222333",
      "wasCreated": false
    },
    {
      "email": "jane.smith@example.com",
      "customerId": "cust_444555666",
      "wasCreated": true
    }
  ]
}

​
Status Codes

CodeDescription
200Device successfully assigned to customers
400Invalid request (missing required fields, invalid email array, or no valid emails)
401Invalid or missing API key
404Device not found (when autoCreateDevice is false)
500Internal server error

​
Implementation Notes

  • Multi-owner support: Assign a single device to multiple customers for shared/family accounts
  • Auto-create customers: Non-existent customers are automatically created using email prefix as name
  • Auto-create devices: Set autoCreateDevice: true and provide deviceType to create devices on-the-fly
  • Email handling: Emails are trimmed, lowercased, and validated. Invalid emails are skipped
  • Idempotent: Re-assigning an already-assigned device won’t create duplicates
Required: When autoCreateDevice is true, you must provide deviceType or the request will fail with a 400 error.