> ## 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.

# Assign Device to Owners

> Create device-to-customer mappings

## 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

<ParamField header="x-api-key" type="string" required>
  Your organization's API key
</ParamField>

## Request Body

<ParamField body="deviceIdentifier" type="string" required>
  The unique identifier for the device (e.g., serial number, MAC address)
</ParamField>

<ParamField body="customerEmails" type="array" required>
  Array of customer email addresses to assign the device to. Must contain at least one valid email.
</ParamField>

<ParamField body="autoCreateDevice" type="boolean" default={false}>
  If `true`, creates the device automatically if it doesn't exist in the system. Defaults to `false`.
</ParamField>

<ParamField body="deviceType" type="string">
  **Required when `autoCreateDevice` is `true`**. Specifies the device type (e.g., "Thermostat", "Sensor", "Gateway"). This field is mandatory for creating new devices.
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Indicates if the operation was successful
</ResponseField>

<ResponseField name="message" type="string">
  Description of the operation result
</ResponseField>

<ResponseField name="deviceId" type="string">
  The unique device ID in the Telemetron system
</ResponseField>

<ResponseField name="deviceWasCreated" type="boolean">
  Indicates whether the device was created during this operation. Always present in the response.
</ResponseField>

<ResponseField name="assignedCustomers" type="array">
  Array of customer objects that were assigned the device

  <Expandable title="Customer Object">
    <ResponseField name="email" type="string">
      Customer's email address
    </ResponseField>

    <ResponseField name="customerId" type="string">
      The customer's unique identifier
    </ResponseField>

    <ResponseField name="wasCreated" type="boolean">
      Indicates if this customer was created during this operation
    </ResponseField>
  </Expandable>
</ResponseField>

## Examples

### Single Customer Assignment

<CodeGroup>
  ```bash cURL theme={null}
  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"]
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://admin.telemetron.ai/api/ext-v1/deviceAssignment/assignDeviceToOwners',
    {
      method: 'POST',
      headers: {
        'x-api-key': 'your_api_key_here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        deviceIdentifier: 'SN-12345-ABCDE',
        customerEmails: ['john.doe@example.com']
      })
    }
  );

  const result = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://admin.telemetron.ai/api/ext-v1/deviceAssignment/assignDeviceToOwners',
      headers={
          'x-api-key': 'your_api_key_here',
          'Content-Type': 'application/json'
      },
      json={
          'deviceIdentifier': 'SN-12345-ABCDE',
          'customerEmails': ['john.doe@example.com']
      }
  )

  result = response.json()
  ```
</CodeGroup>

### Bulk Assignment (Multiple Customers)

<CodeGroup>
  ```bash cURL theme={null}
  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"
      ]
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://admin.telemetron.ai/api/ext-v1/deviceAssignment/assignDeviceToOwners',
    {
      method: 'POST',
      headers: {
        'x-api-key': 'your_api_key_here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        deviceIdentifier: 'SN-12345-ABCDE',
        customerEmails: [
          'john.doe@example.com',
          'jane.smith@example.com'
        ]
      })
    }
  );

  const result = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://admin.telemetron.ai/api/ext-v1/deviceAssignment/assignDeviceToOwners',
      headers={
          'x-api-key': 'your_api_key_here',
          'Content-Type': 'application/json'
      },
      json={
          'deviceIdentifier': 'SN-12345-ABCDE',
          'customerEmails': [
              'john.doe@example.com',
              'jane.smith@example.com'
          ]
      }
  )

  result = response.json()
  ```
</CodeGroup>

### Auto-Create Device

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://admin.telemetron.ai/api/ext-v1/deviceAssignment/assignDeviceToOwners',
    {
      method: 'POST',
      headers: {
        'x-api-key': 'your_api_key_here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        deviceIdentifier: 'SN-67890-FGHIJ',
        customerEmails: ['john.doe@example.com'],
        autoCreateDevice: true,
        deviceType: 'Thermostat'
      })
    }
  );

  const result = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://admin.telemetron.ai/api/ext-v1/deviceAssignment/assignDeviceToOwners',
      headers={
          'x-api-key': 'your_api_key_here',
          'Content-Type': 'application/json'
      },
      json={
          'deviceIdentifier': 'SN-67890-FGHIJ',
          'customerEmails': ['john.doe@example.com'],
          'autoCreateDevice': True,
          'deviceType': 'Thermostat'
      }
  )

  result = response.json()
  ```
</CodeGroup>

### Response

<CodeGroup>
  ```json Success - Existing Device theme={null}
  {
    "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
      }
    ]
  }
  ```

  ```json Success - With Auto-Created Device theme={null}
  {
    "success": true,
    "message": "Successfully assigned device to 1 customer(s)",
    "deviceId": "dev_x1y2z3w4v5",
    "deviceWasCreated": true,
    "assignedCustomers": [
      {
        "email": "new.customer@example.com",
        "customerId": "cust_777888999",
        "wasCreated": true
      }
    ]
  }
  ```

  ```json Error - Device Not Found theme={null}
  {
    "error": "Device not found with the provided identifier. Set autoCreateDevice to true to create it automatically."
  }
  ```

  ```json Error - Missing Device Type theme={null}
  {
    "error": "deviceType is required when creating a new device"
  }
  ```
</CodeGroup>

<RequestExample>
  ```bash cURL - Single Customer Assignment theme={null}
  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"]
    }'
  ```

  ```bash cURL - Bulk Assignment theme={null}
  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"
      ]
    }'
  ```

  ```bash cURL - Auto-Create Device theme={null}
  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"
    }'
  ```

  ```bash cURL - Auto-Create Customers theme={null}
  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": ["new.customer@example.com"]
    }'
  ```

  ```javascript JavaScript - Single Customer Assignment theme={null}
  const response = await fetch(
    'https://admin.telemetron.ai/api/ext-v1/deviceAssignment/assignDeviceToOwners',
    {
      method: 'POST',
      headers: {
        'x-api-key': 'your_api_key_here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        deviceIdentifier: 'SN-12345-ABCDE',
        customerEmails: ['john.doe@example.com']
      })
    }
  );

  const result = await response.json();
  ```

  ```javascript JavaScript - Bulk Assignment theme={null}
  const response = await fetch(
    'https://admin.telemetron.ai/api/ext-v1/deviceAssignment/assignDeviceToOwners',
    {
      method: 'POST',
      headers: {
        'x-api-key': 'your_api_key_here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        deviceIdentifier: 'SN-12345-ABCDE',
        customerEmails: [
          'john.doe@example.com',
          'jane.smith@example.com'
        ]
      })
    }
  );

  const result = await response.json();
  ```

  ```javascript JavaScript - Auto-Create Device theme={null}
  const response = await fetch(
    'https://admin.telemetron.ai/api/ext-v1/deviceAssignment/assignDeviceToOwners',
    {
      method: 'POST',
      headers: {
        'x-api-key': 'your_api_key_here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        deviceIdentifier: 'SN-67890-FGHIJ',
        customerEmails: ['john.doe@example.com'],
        autoCreateDevice: true,
        deviceType: 'Thermostat'
      })
    }
  );

  const result = await response.json();
  ```

  ```javascript JavaScript - Auto-Create Customers theme={null}
  const response = await fetch(
    'https://admin.telemetron.ai/api/ext-v1/deviceAssignment/assignDeviceToOwners',
    {
      method: 'POST',
      headers: {
        'x-api-key': 'your_api_key_here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        deviceIdentifier: 'SN-12345-ABCDE',
        customerEmails: ['new.customer@example.com']
      })
    }
  );

  const result = await response.json();
  ```

  ```python Python - Single Customer Assignment theme={null}
  import requests

  response = requests.post(
      'https://admin.telemetron.ai/api/ext-v1/deviceAssignment/assignDeviceToOwners',
      headers={
          'x-api-key': 'your_api_key_here',
          'Content-Type': 'application/json'
      },
      json={
          'deviceIdentifier': 'SN-12345-ABCDE',
          'customerEmails': ['john.doe@example.com']
      }
  )

  result = response.json()
  ```

  ```python Python - Bulk Assignment theme={null}
  import requests

  response = requests.post(
      'https://admin.telemetron.ai/api/ext-v1/deviceAssignment/assignDeviceToOwners',
      headers={
          'x-api-key': 'your_api_key_here',
          'Content-Type': 'application/json'
      },
      json={
          'deviceIdentifier': 'SN-12345-ABCDE',
          'customerEmails': [
              'john.doe@example.com',
              'jane.smith@example.com'
          ]
      }
  )

  result = response.json()
  ```

  ```python Python - Auto-Create Device theme={null}
  import requests

  response = requests.post(
      'https://admin.telemetron.ai/api/ext-v1/deviceAssignment/assignDeviceToOwners',
      headers={
          'x-api-key': 'your_api_key_here',
          'Content-Type': 'application/json'
      },
      json={
          'deviceIdentifier': 'SN-67890-FGHIJ',
          'customerEmails': ['john.doe@example.com'],
          'autoCreateDevice': True,
          'deviceType': 'Thermostat'
      }
  )

  result = response.json()
  ```

  ```python Python - Auto-Create Customers theme={null}
  import requests

  response = requests.post(
      'https://admin.telemetron.ai/api/ext-v1/deviceAssignment/assignDeviceToOwners',
      headers={
          'x-api-key': 'your_api_key_here',
          'Content-Type': 'application/json'
      },
      json={
          'deviceIdentifier': 'SN-12345-ABCDE',
          'customerEmails': ['new.customer@example.com']
      }
  )

  result = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json Success - Existing Device theme={null}
  {
    "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
      }
    ]
  }
  ```

  ```json Success - With Auto-Created Device theme={null}
  {
    "success": true,
    "message": "Successfully assigned device to 1 customer(s)",
    "deviceId": "dev_x1y2z3w4v5",
    "deviceWasCreated": true,
    "assignedCustomers": [
      {
        "email": "new.customer@example.com",
        "customerId": "cust_777888999",
        "wasCreated": true
      }
    ]
  }
  ```

  ```json Error - Device Not Found theme={null}
  {
    "error": "Device not found with the provided identifier. Set autoCreateDevice to true to create it automatically."
  }
  ```

  ```json Error - Missing Device Type theme={null}
  {
    "error": "deviceType is required when creating a new device"
  }
  ```

  ```json Error - Invalid Emails theme={null}
  {
    "error": "No valid customer emails provided"
  }
  ```
</ResponseExample>

## Status Codes

| Code | Description                                                                        |
| ---- | ---------------------------------------------------------------------------------- |
| 200  | Device successfully assigned to customers                                          |
| 400  | Invalid request (missing required fields, invalid email array, or no valid emails) |
| 401  | Invalid or missing API key                                                         |
| 404  | Device not found (when autoCreateDevice is false)                                  |
| 500  | Internal 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

<Warning>
  **Required**: When `autoCreateDevice` is `true`, you **must** provide `deviceType` or the request will fail with a 400 error.
</Warning>