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

# API Getting Started

> Sync devices, customers, and ownership mappings into Telemetron

## What This API Does

Telemetron provides AI-powered support for hardware companies. This API lets you sync three things:

1. **Devices** - Your hardware products that send telemetry
2. **Customers** - Your end users who own devices
3. **Device Assignments** - Mappings that connect devices to customers

When devices send telemetry to Telemetron, we use these mappings to identify which customer owns the device and provide intelligent support.

<Tip>
  **Flow**: Device sends telemetry → Telemetron looks up assignment → Identifies customer → Provides AI-powered support
</Tip>

## Quick Integration

<Steps>
  <Step title="Get Your API Key">
    Log into your [Dashboard](https://admin.telemetron.ai) and go to the [Integrations page](https://admin.telemetron.ai/dashboard/settings/integrations) → scroll down to find your API key and copy it

    All API requests require your key in the header:

    ```bash theme={null}
    x-api-key: your_api_key_here
    ```

    <Warning>Keep your API key secure. Never expose it in client-side code or commit it to version control.</Warning>
  </Step>

  <Step title="Create a Customer">
    Sync customer information to Telemetron:

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST https://admin.telemetron.ai/api/ext-v1/customer/createOrUpdateCustomer \
        -H "x-api-key: your_api_key_here" \
        -H "Content-Type: application/json" \
        -d '{
          "name": "John Doe",
          "email": "john.doe@example.com",
          "phone": "+1234567890",
          "address": "123 Main St, City, State 12345"
        }'
      ```

      ```javascript JavaScript theme={null}
      const response = await fetch(
        'https://admin.telemetron.ai/api/ext-v1/customer/createOrUpdateCustomer',
        {
          method: 'POST',
          headers: {
            'x-api-key': 'your_api_key_here',
            'Content-Type': 'application/json'
          },
          body: JSON.stringify({
            name: 'John Doe',
            email: 'john.doe@example.com',
            phone: '+1234567890',
            address: '123 Main St, City, State 12345'
          })
        }
      );

      const customer = await response.json();
      console.log('Customer ID:', customer.telemetronCustomerId);
      ```

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

      response = requests.post(
          'https://admin.telemetron.ai/api/ext-v1/customer/createOrUpdateCustomer',
          headers={
              'x-api-key': 'your_api_key_here',
              'Content-Type': 'application/json'
          },
          json={
              'name': 'John Doe',
              'email': 'john.doe@example.com',
              'phone': '+1234567890',
              'address': '123 Main St, City, State 12345'
          }
      )

      customer = response.json()
      print('Customer ID:', customer['telemetronCustomerId'])
      ```
    </CodeGroup>
  </Step>

  <Step title="Assign a Device to the Customer">
    Create the device-to-customer mapping for telemetry routing:

    <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"],
          "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-12345-ABCDE',
            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-12345-ABCDE',
              'customerEmails': ['john.doe@example.com'],
              'autoCreateDevice': True,
              'deviceType': 'Thermostat'
          }
      )

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

    <Info>
      Set `autoCreateDevice: true` to automatically create the device if it doesn't exist. When using this option, you **must** provide `deviceType`.
    </Info>
  </Step>

  <Step title="Done">
    Telemetry from `SN-12345-ABCDE` now routes to `john.doe@example.com` for AI-powered support.
  </Step>
</Steps>

## Common Scenarios

<AccordionGroup>
  <Accordion title="Customer buys a device" icon="cart-shopping">
    1. Customer completes purchase in your system
    2. Call [Create Customer](/api-reference/customer/create-or-update) if the customer is new
    3. Call [Assign Device](/api-reference/device/assign-device) with `autoCreateDevice: true` and `deviceType`
    4. Telemetry from this device now routes to this customer
  </Accordion>

  <Accordion title="Customer sells device to someone else" icon="right-left">
    1. Call [Unassign Device](/api-reference/device/unassign-device) with the old owner's email
    2. Call [Create Customer](/api-reference/customer/create-or-update) for the new owner if needed
    3. Call [Assign Device](/api-reference/device/assign-device) with the new owner's email
    4. Telemetry now routes to the new owner
  </Accordion>

  <Accordion title="Family shares a device" icon="users">
    1. Ensure all family members exist as customers
    2. Call [Assign Device](/api-reference/device/assign-device) with an array of all family member emails
    3. All family members receive support alerts for this device
  </Accordion>
</AccordionGroup>

## API Endpoints

<CardGroup cols={2}>
  <Card title="Customer Management" icon="users" href="/api-reference/customer/create-or-update">
    Create, update, and query customer records.
  </Card>

  <Card title="Device Management" icon="microchip" href="/api-reference/device/create-or-update-device">
    Register and update devices.
  </Card>

  <Card title="Device Assignment" icon="link" href="/api-reference/device/assign-device">
    Map devices to customers for telemetry routing.
  </Card>

  <Card title="API Reference Overview" icon="book" href="/api-reference/introduction">
    Review the base URL, authentication model, response format, and endpoint catalog.
  </Card>
</CardGroup>