# Find User Device

Finds a device in SimpleMDM by user email or serial number

Locates devices in SimpleMDM by email or serial number, returning basic device information and the device_id for use with other SimpleMDM tools.

## Overview

This tool searches for devices using multiple methods: serial number lookup, device name patterns, custom attributes, or email prefix matching. It's the foundational tool for SimpleMDM operations, as other tools require the device_id it returns.

## Setup

### Create API Key

1. Sign into SimpleMDM at `https://app.simplemdm.com`
2. Navigate to **Settings** > **API**
3. Click **New API Key**
4. Name it (e.g., "Risotto Integration")
5. Copy the API key immediately (shown only once)

> **Warning:** Save the API key securely. It cannot be viewed again after creation.

### Configure in Risotto

In the Risotto dashboard, select **Tools** in the sidebar. Select **SimpleMDM** in the **Tool groups** list. Find **SimpleMDM Find User Device** and click **Set up**. Fill in this field, then click **Save**:

| Field       | Description            | Example                |
| ----------- | ---------------------- | ---------------------- |
| **Api Key** | Your SimpleMDM API key | `a1b2c3d4e5f6g7h8i9j0` |

### Optional: Configure Search Methods

For better results, configure device name patterns to match your naming conventions:

```json
{
  "device_name_patterns": [
    "{email}",
    "{username}",
    "{username}-laptop",
    "{username}-macbook"
  ]
}
```

Variables: `{email}` = full email, `{username}` = part before @

## Usage

**Search by email:**

> "Find SimpleMDM device for <john.smith@company.com>"

**Search by serial number:**

> "Find SimpleMDM device with serial number C02XY1ZHJG5H"

**Get device_id only (for chaining with other tools):**

> "Find device for <sarah@company.com> with return_device_id_only=true"

## Response Format

Returns device information including:

- Device ID (for use with other tools)
- Device name, model, serial number
- OS version and enrollment status
- Last seen timestamp

## Search Methods

The tool tries these methods in order:

1. **Serial Number** - Most reliable, works for any device
2. **Device Name Patterns** - Matches configured patterns with user email/username
3. **Custom Attribute** - Searches SimpleMDM custom attributes for user email
4. **Email Prefix** - Fallback search using username portion of email

## Troubleshooting

**No device found for email:**

- Verify device is enrolled in SimpleMDM
- Check device naming matches configured patterns
- Try searching by serial number instead
- Add more patterns to `device_name_patterns`

**No device found by serial:**

- Verify serial number is correct
- Confirm device is enrolled in SimpleMDM

**Authentication errors:**

- Verify API key is correct
- Check key hasn't been revoked in SimpleMDM settings
- Create a new API key if needed

## Security Notes

- API keys use HTTP Basic Authentication (key as username, blank password)
- All requests must be over HTTPS
- Store API keys securely
- Rotate keys periodically (every 90 days recommended)
- Revoke unused keys in **Settings** > **API**

## Related Tools

- **SimpleMDM Get Device Information** - Detailed specs, apps, profiles (requires device_id)
- **SimpleMDM Refresh Device Inventory** - Update app inventory (requires device_id)
- **SimpleMDM Push Assigned Apps** - Install apps (requires device_id)

Source: https://www.tryrisotto.com/docs/integrations/tools/simplemdm/find_user_device
