> ## 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 Devices to Owner

> Assign multiple devices to a single customer

## Overview

Assigns multiple devices to a single customer in one request. This is the bulk variant for assigning devices — use this when provisioning several devices for the same customer.

**Features:**

* Assign multiple devices to one customer in a single call
* Auto-creates the customer if they don't exist
* Optional auto-create for devices (requires `deviceType`)
* Reports which devices were newly assigned, already assigned, or skipped

## Authentication

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

## Request Body

<ParamField body="customerEmail" type="string" required>
  The email address of the customer to assign devices to. Must be a valid email format.
</ParamField>

<ParamField body="deviceIdentifiers" type="array" required>
  Array of device identifiers (e.g., serial numbers, MAC addresses) to assign. Must be a non-empty array.
</ParamField>

<ParamField body="autoCreateDevices" type="boolean" default={false}>
  If `true`, creates devices automatically if they don't exist in the system. Defaults to `false`.
</ParamField>

<ParamField body="deviceType" type="string">
  **Required when `autoCreateDevices` is `true`**. Specifies the device type (e.g., "sensor", "Thermostat", "Gateway").
</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="customerId" type="string">
  The unique identifier of the customer in Telemetron
</ResponseField>

<ResponseField name="customerWasCreated" type="boolean">
  Indicates whether the customer was created during this operation
</ResponseField>

<ResponseField name="assignedDevices" type="array">
  Array of devices that were newly assigned in this request

  <Expandable title="Device Object">
    <ResponseField name="identifier" type="string">
      The device identifier
    </ResponseField>

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

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

<ResponseField name="alreadyAssigned" type="array">
  Array of devices that were already assigned to this customer (no-op)

  <Expandable title="Device Object">
    <ResponseField name="identifier" type="string">
      The device identifier
    </ResponseField>

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

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

<ResponseField name="skipped" type="array">
  Array of device identifier strings that were not found in the system (when `autoCreateDevices` is `false`)
</ResponseField>

## Examples

### Basic Bulk Assignment

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://admin.telemetron.ai/api/ext-v1/deviceAssignment/assignDevicesToOwner \
    -H "x-api-key: your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "customerEmail": "john.doe@example.com",
      "deviceIdentifiers": ["SN-001", "SN-002", "SN-003"]
    }'
  ```

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

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

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

  response = requests.post(
      'https://admin.telemetron.ai/api/ext-v1/deviceAssignment/assignDevicesToOwner',
      headers={
          'x-api-key': 'your_api_key_here',
          'Content-Type': 'application/json'
      },
      json={
          'customerEmail': 'john.doe@example.com',
          'deviceIdentifiers': ['SN-001', 'SN-002', 'SN-003']
      }
  )

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

### With Auto-Create Devices

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://admin.telemetron.ai/api/ext-v1/deviceAssignment/assignDevicesToOwner \
    -H "x-api-key: your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "customerEmail": "john.doe@example.com",
      "deviceIdentifiers": ["SN-001", "SN-002"],
      "autoCreateDevices": true,
      "deviceType": "sensor"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://admin.telemetron.ai/api/ext-v1/deviceAssignment/assignDevicesToOwner',
    {
      method: 'POST',
      headers: {
        'x-api-key': 'your_api_key_here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        customerEmail: 'john.doe@example.com',
        deviceIdentifiers: ['SN-001', 'SN-002'],
        autoCreateDevices: true,
        deviceType: 'sensor'
      })
    }
  );

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

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

  response = requests.post(
      'https://admin.telemetron.ai/api/ext-v1/deviceAssignment/assignDevicesToOwner',
      headers={
          'x-api-key': 'your_api_key_here',
          'Content-Type': 'application/json'
      },
      json={
          'customerEmail': 'john.doe@example.com',
          'deviceIdentifiers': ['SN-001', 'SN-002'],
          'autoCreateDevices': True,
          'deviceType': 'sensor'
      }
  )

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

### Response

<CodeGroup>
  ```json Success - Mixed Results theme={null}
  {
    "success": true,
    "message": "Successfully assigned 2 device(s) to customer",
    "customerId": "cust_abc123",
    "customerWasCreated": false,
    "assignedDevices": [
      { "identifier": "SN-001", "deviceId": "dev_x1y2z3", "wasCreated": false }
    ],
    "alreadyAssigned": [
      { "identifier": "SN-002", "deviceId": "dev_a4b5c6", "wasCreated": false }
    ],
    "skipped": ["SN-003"]
  }
  ```

  ```json Success - New Customer theme={null}
  {
    "success": true,
    "message": "Successfully assigned 2 device(s) to customer",
    "customerId": "cust_new789",
    "customerWasCreated": true,
    "assignedDevices": [
      { "identifier": "SN-001", "deviceId": "dev_x1y2z3", "wasCreated": false },
      { "identifier": "SN-002", "deviceId": "dev_a4b5c6", "wasCreated": true }
    ],
    "alreadyAssigned": [],
    "skipped": []
  }
  ```

  ```json Error - Invalid Input theme={null}
  {
    "error": "Invalid input: customerEmail is required"
  }
  ```
</CodeGroup>

<RequestExample>
  ```bash cURL - Basic Bulk Assignment theme={null}
  curl -X POST https://admin.telemetron.ai/api/ext-v1/deviceAssignment/assignDevicesToOwner \
    -H "x-api-key: your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "customerEmail": "john.doe@example.com",
      "deviceIdentifiers": ["SN-001", "SN-002", "SN-003"]
    }'
  ```

  ```bash cURL - With Auto-Create theme={null}
  curl -X POST https://admin.telemetron.ai/api/ext-v1/deviceAssignment/assignDevicesToOwner \
    -H "x-api-key: your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "customerEmail": "john.doe@example.com",
      "deviceIdentifiers": ["SN-001", "SN-002"],
      "autoCreateDevices": true,
      "deviceType": "sensor"
    }'
  ```

  ```javascript JavaScript - Basic Bulk Assignment theme={null}
  const response = await fetch(
    'https://admin.telemetron.ai/api/ext-v1/deviceAssignment/assignDevicesToOwner',
    {
      method: 'POST',
      headers: {
        'x-api-key': 'your_api_key_here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        customerEmail: 'john.doe@example.com',
        deviceIdentifiers: ['SN-001', 'SN-002', 'SN-003']
      })
    }
  );

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

  ```javascript JavaScript - With Auto-Create theme={null}
  const response = await fetch(
    'https://admin.telemetron.ai/api/ext-v1/deviceAssignment/assignDevicesToOwner',
    {
      method: 'POST',
      headers: {
        'x-api-key': 'your_api_key_here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        customerEmail: 'john.doe@example.com',
        deviceIdentifiers: ['SN-001', 'SN-002'],
        autoCreateDevices: true,
        deviceType: 'sensor'
      })
    }
  );

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

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

  response = requests.post(
      'https://admin.telemetron.ai/api/ext-v1/deviceAssignment/assignDevicesToOwner',
      headers={
          'x-api-key': 'your_api_key_here',
          'Content-Type': 'application/json'
      },
      json={
          'customerEmail': 'john.doe@example.com',
          'deviceIdentifiers': ['SN-001', 'SN-002', 'SN-003']
      }
  )

  result = response.json()
  ```

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

  response = requests.post(
      'https://admin.telemetron.ai/api/ext-v1/deviceAssignment/assignDevicesToOwner',
      headers={
          'x-api-key': 'your_api_key_here',
          'Content-Type': 'application/json'
      },
      json={
          'customerEmail': 'john.doe@example.com',
          'deviceIdentifiers': ['SN-001', 'SN-002'],
          'autoCreateDevices': True,
          'deviceType': 'sensor'
      }
  )

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

<ResponseExample>
  ```json Success - Mixed Results theme={null}
  {
    "success": true,
    "message": "Successfully assigned 2 device(s) to customer",
    "customerId": "cust_abc123",
    "customerWasCreated": false,
    "assignedDevices": [
      { "identifier": "SN-001", "deviceId": "dev_x1y2z3", "wasCreated": false }
    ],
    "alreadyAssigned": [
      { "identifier": "SN-002", "deviceId": "dev_a4b5c6", "wasCreated": false }
    ],
    "skipped": ["SN-003"]
  }
  ```

  ```json Success - All Assigned theme={null}
  {
    "success": true,
    "message": "Successfully assigned 3 device(s) to customer",
    "customerId": "cust_abc123",
    "customerWasCreated": false,
    "assignedDevices": [
      { "identifier": "SN-001", "deviceId": "dev_x1y2z3", "wasCreated": false },
      { "identifier": "SN-002", "deviceId": "dev_a4b5c6", "wasCreated": false },
      { "identifier": "SN-003", "deviceId": "dev_d7e8f9", "wasCreated": true }
    ],
    "alreadyAssigned": [],
    "skipped": []
  }
  ```

  ```json Error - No Valid Devices theme={null}
  {
    "error": "No valid devices found to assign"
  }
  ```

  ```json Error - Missing Device Type theme={null}
  {
    "error": "deviceType is required when autoCreateDevices is true"
  }
  ```
</ResponseExample>

## Status Codes

| Code | Description                                                                 |
| ---- | --------------------------------------------------------------------------- |
| 200  | Devices successfully assigned to customer                                   |
| 400  | Invalid request (missing required fields, empty array, or no valid devices) |
| 401  | Invalid or missing API key                                                  |
| 500  | Internal server error                                                       |

## Implementation Notes

* **Idempotent**: Devices already assigned to the customer are reported in `alreadyAssigned` — no duplicates are created
* **Auto-create customer**: The customer is automatically created if they don't exist
* **Partial success**: The response details which devices were assigned, already assigned, or skipped, allowing you to handle each case
* **Skipped devices**: When `autoCreateDevices` is `false`, unknown device identifiers are returned in the `skipped` array

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