> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getdoppel.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Filtering Interactions

> Master the powerful filtering options to get exactly the data you need

# Filtering Interactions

The interactions endpoint supports powerful filtering options to help you retrieve exactly the data you need. This guide covers common use cases with practical examples.

## Filter Parameters

| Parameter   | Type   | Description                                                                                       |
| ----------- | ------ | ------------------------------------------------------------------------------------------------- |
| `channel`   | string | `voice` or `whatsapp`                                                                             |
| `type`      | string | Interaction type (varies by channel)                                                              |
| `outcome`   | string | Filter by outcome (comma-separated for multiple, e.g., `APPOINTMENT_BOOKED,APPOINTMENT_MODIFIED`) |
| `clinic_id` | string | Specific clinic UUID                                                                              |
| `date_from` | string | Start date (ISO 8601, e.g., `2024-01-15`)                                                         |
| `date_to`   | string | End date (ISO 8601, e.g., `2024-01-31`)                                                           |
| `search`    | string | Search phone numbers (partial match, e.g., `555` matches `+1-555-123-4567`)                       |

## Common Use Cases

### Get All WhatsApp Inbound Messages

Retrieve all incoming WhatsApp conversations from patients:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.getdoppel.ai/api/v1/interactions?channel=whatsapp&type=INBOUND" \
    -H "Authorization: Bearer dpl_live_YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.getdoppel.ai/api/v1/interactions?channel=whatsapp&type=INBOUND',
    {
      headers: {
        'Authorization': 'Bearer dpl_live_YOUR_API_KEY'
      }
    }
  );
  ```

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

  response = requests.get(
      'https://api.getdoppel.ai/api/v1/interactions',
      params={
          'channel': 'whatsapp',
          'type': 'INBOUND'
      },
      headers={'Authorization': 'Bearer dpl_live_YOUR_API_KEY'}
  )
  ```
</CodeGroup>

***

### Get Voice Campaign Outbound Calls

Retrieve all outbound calls from campaigns (e.g., no-show recovery, reactivation):

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.getdoppel.ai/api/v1/interactions?channel=voice&type=CAMPAIGN_OUTBOUND" \
    -H "Authorization: Bearer dpl_live_YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.getdoppel.ai/api/v1/interactions?channel=voice&type=CAMPAIGN_OUTBOUND',
    {
      headers: {
        'Authorization': 'Bearer dpl_live_YOUR_API_KEY'
      }
    }
  );
  ```

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

  response = requests.get(
      'https://api.getdoppel.ai/api/v1/interactions',
      params={
          'channel': 'voice',
          'type': 'CAMPAIGN_OUTBOUND'
      },
      headers={'Authorization': 'Bearer dpl_live_YOUR_API_KEY'}
  )
  ```
</CodeGroup>

***

### Get All Appointment Reminders

Retrieve WhatsApp appointment reminder conversations:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.getdoppel.ai/api/v1/interactions?type=APPOINTMENT_REMINDER" \
    -H "Authorization: Bearer dpl_live_YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.getdoppel.ai/api/v1/interactions?type=APPOINTMENT_REMINDER',
    {
      headers: {
        'Authorization': 'Bearer dpl_live_YOUR_API_KEY'
      }
    }
  );
  ```

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

  response = requests.get(
      'https://api.getdoppel.ai/api/v1/interactions',
      params={'type': 'APPOINTMENT_REMINDER'},
      headers={'Authorization': 'Bearer dpl_live_YOUR_API_KEY'}
  )
  ```
</CodeGroup>

***

### Get All Inbound Calls

Retrieve all incoming voice calls:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.getdoppel.ai/api/v1/interactions?channel=voice&type=INBOUND" \
    -H "Authorization: Bearer dpl_live_YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.getdoppel.ai/api/v1/interactions?channel=voice&type=INBOUND',
    {
      headers: {
        'Authorization': 'Bearer dpl_live_YOUR_API_KEY'
      }
    }
  );
  ```

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

  response = requests.get(
      'https://api.getdoppel.ai/api/v1/interactions',
      params={
          'channel': 'voice',
          'type': 'INBOUND'
      },
      headers={'Authorization': 'Bearer dpl_live_YOUR_API_KEY'}
  )
  ```
</CodeGroup>

***

### Get Interactions for a Date Range

Retrieve interactions within a specific date range:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.getdoppel.ai/api/v1/interactions?date_from=2024-01-01&date_to=2024-01-31" \
    -H "Authorization: Bearer dpl_live_YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.getdoppel.ai/api/v1/interactions?date_from=2024-01-01&date_to=2024-01-31',
    {
      headers: {
        'Authorization': 'Bearer dpl_live_YOUR_API_KEY'
      }
    }
  );
  ```

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

  response = requests.get(
      'https://api.getdoppel.ai/api/v1/interactions',
      params={
          'date_from': '2024-01-01',
          'date_to': '2024-01-31'
      },
      headers={'Authorization': 'Bearer dpl_live_YOUR_API_KEY'}
  )
  ```
</CodeGroup>

***

### Get Interactions by Outcome

Filter by specific outcomes (e.g., new bookings):

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.getdoppel.ai/api/v1/interactions?outcome=APPOINTMENT_BOOKED" \
    -H "Authorization: Bearer dpl_live_YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.getdoppel.ai/api/v1/interactions?outcome=APPOINTMENT_BOOKED',
    {
      headers: {
        'Authorization': 'Bearer dpl_live_YOUR_API_KEY'
      }
    }
  );
  ```

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

  response = requests.get(
      'https://api.getdoppel.ai/api/v1/interactions',
      params={'outcome': 'APPOINTMENT_BOOKED'},
      headers={'Authorization': 'Bearer dpl_live_YOUR_API_KEY'}
  )
  ```
</CodeGroup>

***

### Filter by Clinic

Get interactions for a specific clinic:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.getdoppel.ai/api/v1/interactions?clinic_id=550e8400-e29b-41d4-a716-446655440000" \
    -H "Authorization: Bearer dpl_live_YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.getdoppel.ai/api/v1/interactions?clinic_id=550e8400-e29b-41d4-a716-446655440000',
    {
      headers: {
        'Authorization': 'Bearer dpl_live_YOUR_API_KEY'
      }
    }
  );
  ```

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

  response = requests.get(
      'https://api.getdoppel.ai/api/v1/interactions',
      params={'clinic_id': '550e8400-e29b-41d4-a716-446655440000'},
      headers={'Authorization': 'Bearer dpl_live_YOUR_API_KEY'}
  )
  ```
</CodeGroup>

***

### Combine Multiple Filters

You can combine multiple filters for precise queries:

<CodeGroup>
  ```bash cURL theme={null}
  # Get WhatsApp campaign messages from January 2024 for a specific clinic
  curl -X GET "https://api.getdoppel.ai/api/v1/interactions?channel=whatsapp&type=CAMPAIGN_OUTBOUND&date_from=2024-01-01&date_to=2024-01-31&clinic_id=550e8400-e29b-41d4-a716-446655440000" \
    -H "Authorization: Bearer dpl_live_YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    channel: 'whatsapp',
    type: 'CAMPAIGN_OUTBOUND',
    date_from: '2024-01-01',
    date_to: '2024-01-31',
    clinic_id: '550e8400-e29b-41d4-a716-446655440000'
  });

  const response = await fetch(
    `https://api.getdoppel.ai/api/v1/interactions?${params}`,
    {
      headers: {
        'Authorization': 'Bearer dpl_live_YOUR_API_KEY'
      }
    }
  );
  ```

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

  response = requests.get(
      'https://api.getdoppel.ai/api/v1/interactions',
      params={
          'channel': 'whatsapp',
          'type': 'CAMPAIGN_OUTBOUND',
          'date_from': '2024-01-01',
          'date_to': '2024-01-31',
          'clinic_id': '550e8400-e29b-41d4-a716-446655440000'
      },
      headers={'Authorization': 'Bearer dpl_live_YOUR_API_KEY'}
  )
  ```
</CodeGroup>

***

## Pagination

When dealing with large datasets, use pagination:

```bash theme={null}
# Get page 2 with 50 items per page
curl -X GET "https://api.getdoppel.ai/api/v1/interactions?page=2&limit=50" \
  -H "Authorization: Bearer dpl_live_YOUR_API_KEY"
```

### Iterating Through All Pages

<CodeGroup>
  ```javascript JavaScript theme={null}
  async function getAllInteractions(apiKey, filters = {}) {
    const interactions = [];
    let page = 1;
    let hasMore = true;

    while (hasMore) {
      const params = new URLSearchParams({
        ...filters,
        page: page.toString(),
        limit: '100'
      });

      const response = await fetch(
        `https://api.getdoppel.ai/api/v1/interactions?${params}`,
        {
          headers: {
            'Authorization': `Bearer ${apiKey}`
          }
        }
      );

      const data = await response.json();
      interactions.push(...data.data.interactions);

      hasMore = data.meta.has_more;
      page++;
    }

    return interactions;
  }

  // Usage: Get all WhatsApp inbounds
  const allWhatsAppInbounds = await getAllInteractions('dpl_live_YOUR_API_KEY', {
    channel: 'whatsapp',
    type: 'INBOUND'
  });
  ```

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

  def get_all_interactions(api_key, **filters):
      interactions = []
      page = 1
      has_more = True

      while has_more:
          response = requests.get(
              'https://api.getdoppel.ai/api/v1/interactions',
              params={**filters, 'page': page, 'limit': 100},
              headers={'Authorization': f'Bearer {api_key}'}
          )
          data = response.json()

          interactions.extend(data['data']['interactions'])
          has_more = data['meta']['has_more']
          page += 1

      return interactions

  # Usage: Get all voice campaign outbounds
  all_campaign_calls = get_all_interactions(
      'dpl_live_YOUR_API_KEY',
      channel='voice',
      type='CAMPAIGN_OUTBOUND'
  )
  ```
</CodeGroup>

***

## Search by Phone Number

Use the `search` parameter to find interactions by phone number. Search uses **partial matching** - any phone number containing your search term will be returned.

<CodeGroup>
  ```bash cURL theme={null}
  # Search for interactions with phone numbers containing "555"
  curl -X GET "https://api.getdoppel.ai/api/v1/interactions?search=555" \
    -H "Authorization: Bearer dpl_live_YOUR_API_KEY"

  # Search for a specific phone number (URL-encode the + as %2B)
  curl -X GET "https://api.getdoppel.ai/api/v1/interactions?search=%2B34612345678" \
    -H "Authorization: Bearer dpl_live_YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  // Search for partial phone number
  const response = await fetch(
    'https://api.getdoppel.ai/api/v1/interactions?search=555',
    {
      headers: {
        'Authorization': 'Bearer dpl_live_YOUR_API_KEY'
      }
    }
  );

  // Search for specific phone number
  const response2 = await fetch(
    'https://api.getdoppel.ai/api/v1/interactions?search=' + encodeURIComponent('+34612345678'),
    {
      headers: {
        'Authorization': 'Bearer dpl_live_YOUR_API_KEY'
      }
    }
  );
  ```

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

  # Search for partial phone number
  response = requests.get(
      'https://api.getdoppel.ai/api/v1/interactions',
      params={'search': '555'},
      headers={'Authorization': 'Bearer dpl_live_YOUR_API_KEY'}
  )

  # Search for specific phone number
  response = requests.get(
      'https://api.getdoppel.ai/api/v1/interactions',
      params={'search': '+34612345678'},
      headers={'Authorization': 'Bearer dpl_live_YOUR_API_KEY'}
  )
  ```
</CodeGroup>

<Info>
  The `search` parameter is case-insensitive and matches any part of the phone number. For example, `search=555` will match `+1-555-123-4567`, `555-1234`, etc.
</Info>

***

## Multi-Outcome Filtering

Filter interactions by multiple outcomes at once using comma-separated values. This is useful for getting all appointment-related interactions in a single request.

<CodeGroup>
  ```bash cURL theme={null}
  # Get all appointment-related interactions (booked, modified, or cancelled)
  curl -X GET "https://api.getdoppel.ai/api/v1/interactions?outcome=APPOINTMENT_BOOKED,APPOINTMENT_MODIFIED,APPOINTMENT_CANCELLED" \
    -H "Authorization: Bearer dpl_live_YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.getdoppel.ai/api/v1/interactions?outcome=APPOINTMENT_BOOKED,APPOINTMENT_MODIFIED,APPOINTMENT_CANCELLED',
    {
      headers: {
        'Authorization': 'Bearer dpl_live_YOUR_API_KEY'
      }
    }
  );
  ```

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

  response = requests.get(
      'https://api.getdoppel.ai/api/v1/interactions',
      params={'outcome': 'APPOINTMENT_BOOKED,APPOINTMENT_MODIFIED,APPOINTMENT_CANCELLED'},
      headers={'Authorization': 'Bearer dpl_live_YOUR_API_KEY'}
  )
  ```
</CodeGroup>

### Valid Outcome Values

| Outcome                 | Description                          |
| ----------------------- | ------------------------------------ |
| `APPOINTMENT_BOOKED`    | New appointment was scheduled        |
| `APPOINTMENT_MODIFIED`  | Existing appointment was rescheduled |
| `APPOINTMENT_CANCELLED` | Appointment was cancelled            |
| `NO_ANSWER`             | Call was not answered                |
| `VOICEMAIL_REACHED`     | Call went to voicemail               |
| `CALLBACK_REQUESTED`    | Patient requested a callback         |
| `OPT_OUT`               | Patient opted out of communications  |
| `DECISION_PENDING`      | Patient needs more time to decide    |

<Info>
  Outcome values are **case-sensitive** and must be **UPPERCASE**. Invalid values will return a 400 validation error.
</Info>

***

## Get All Bookings

A common use case is retrieving all appointment-related interactions from a date range:

<CodeGroup>
  ```bash cURL theme={null}
  # Get all bookings and modifications from the last 30 days
  curl -X GET "https://api.getdoppel.ai/api/v1/interactions?outcome=APPOINTMENT_BOOKED,APPOINTMENT_MODIFIED,APPOINTMENT_CANCELLED&date_from=2024-12-06&date_to=2025-01-05" \
    -H "Authorization: Bearer dpl_live_YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  // Get all appointment-related interactions from last 30 days
  const today = new Date();
  const thirtyDaysAgo = new Date(today);
  thirtyDaysAgo.setDate(thirtyDaysAgo.getDate() - 30);

  const params = new URLSearchParams({
    outcome: 'APPOINTMENT_BOOKED,APPOINTMENT_MODIFIED,APPOINTMENT_CANCELLED',
    date_from: thirtyDaysAgo.toISOString().split('T')[0],
    date_to: today.toISOString().split('T')[0]
  });

  const response = await fetch(
    `https://api.getdoppel.ai/api/v1/interactions?${params}`,
    {
      headers: {
        'Authorization': 'Bearer dpl_live_YOUR_API_KEY'
      }
    }
  );
  const { data } = await response.json();

  console.log(`Found ${data.interactions.length} appointment interactions`);
  ```

  ```python Python theme={null}
  import requests
  from datetime import datetime, timedelta

  today = datetime.now()
  thirty_days_ago = today - timedelta(days=30)

  response = requests.get(
      'https://api.getdoppel.ai/api/v1/interactions',
      params={
          'outcome': 'APPOINTMENT_BOOKED,APPOINTMENT_MODIFIED,APPOINTMENT_CANCELLED',
          'date_from': thirty_days_ago.strftime('%Y-%m-%d'),
          'date_to': today.strftime('%Y-%m-%d')
      },
      headers={'Authorization': 'Bearer dpl_live_YOUR_API_KEY'}
  )
  data = response.json()

  print(f"Found {len(data['data']['interactions'])} appointment interactions")
  ```
</CodeGroup>

***

## Quick Reference: Filter Combinations

| Use Case                    | Filters                                                                 |
| --------------------------- | ----------------------------------------------------------------------- |
| All inbound calls           | `channel=voice&type=INBOUND`                                            |
| All outbound campaign calls | `channel=voice&type=CAMPAIGN_OUTBOUND`                                  |
| Callback calls              | `channel=voice&type=CAMPAIGN_CALLBACK`                                  |
| Form-triggered calls        | `channel=voice&type=FORM_OUTBOUND`                                      |
| All inbound WhatsApp        | `channel=whatsapp&type=INBOUND`                                         |
| WhatsApp campaigns          | `channel=whatsapp&type=CAMPAIGN_OUTBOUND`                               |
| Appointment reminders       | `type=APPOINTMENT_REMINDER`                                             |
| New bookings                | `outcome=APPOINTMENT_BOOKED`                                            |
| All appointment changes     | `outcome=APPOINTMENT_BOOKED,APPOINTMENT_MODIFIED,APPOINTMENT_CANCELLED` |
| Last 30 days                | `date_from=2024-12-06&date_to=2025-01-05`                               |
| Search by phone             | `search=555` (partial match)                                            |