Filtering

Learn how to filter and search resources in the Audian API to find exactly what you need.

Overview

Most list endpoints support filtering to narrow down results. Pass filter parameters as query strings:

GET /accounts/{ACCOUNT_ID}/users?filter_status=enabled

Basic Filtering

Simple Equality

Filter by exact match:

# Get enabled users
GET /accounts/{ACCOUNT_ID}/users?filter_status=enabled

# Get SIP devices
GET /accounts/{ACCOUNT_ID}/devices?filter_device_type=sip_device

# Get inbound call records
GET /accounts/{ACCOUNT_ID}/cdrs?filter_direction=inbound

Multiple Values

Filter by multiple values of the same field:

# Get users that are enabled or disabled
GET /accounts/{ACCOUNT_ID}/users?filter_status=enabled&filter_status=disabled

Date Filtering

Filter call detail records by date ranges using Gregorian seconds:

# CDRs from a specific date range
GET /accounts/{ACCOUNT_ID}/cdrs?created_from=63781142400&created_to=63781228800

Converting Dates

Gregorian seconds is the number of seconds since year 0. To convert:

from datetime import datetime

# Convert datetime to Gregorian seconds
def to_gregorian(dt):
    epoch = datetime(1, 1, 1)
    return int((dt - epoch).total_seconds())

# Example: February 1, 2025
dt = datetime(2025, 2, 1)
gregorian = to_gregorian(dt)  # 63876672000

Resource-Specific Filters

User Filters

Parameter	Description
filter_status	Filter by status (enabled, disabled)
filter_username	Filter by username
filter_first_name	Filter by first name
filter_last_name	Filter by last name

Device Filters

Parameter	Description
filter_device_type	Filter by type (sip_device, softphone, cellphone)
filter_enabled	Filter by enabled status
filter_owner_id	Filter by owner user ID

CDR Filters

Parameter	Description
created_from	Start timestamp (Gregorian seconds)
created_to	End timestamp (Gregorian seconds)
filter_direction	Call direction (inbound, outbound)
filter_hangup_cause	Filter by hangup cause
filter_caller_id_number	Filter by caller ID
filter_callee_id_number	Filter by callee number

Phone Number Filters

Parameter	Description
filter_state	Number state (in_service, port_in, etc.)

Code Examples

Python - Filter Users

import requests

API_KEY = 'your_api_key'
ACCOUNT_ID = 'your_account_id'

# Get enabled users
response = requests.get(
    f'https://api.audian.com:8443/v2/accounts/{ACCOUNT_ID}/users',
    headers={'X-Auth-Token': API_KEY},
    params={'filter_status': 'enabled'}
)

users = response.json()['data']
print(f"Found {len(users)} enabled users")

Python - Filter CDRs by Date

import requests

API_KEY = 'your_api_key'
ACCOUNT_ID = 'your_account_id'

# Get CDRs from a specific date range
response = requests.get(
    f'https://api.audian.com:8443/v2/accounts/{ACCOUNT_ID}/cdrs',
    headers={'X-Auth-Token': API_KEY},
    params={
        'created_from': '63876672000',
        'created_to': '63876758400',
        'page_size': 50
    }
)

cdrs = response.json()['data']
print(f"Found {len(cdrs)} call records")

Node.js - Filter Devices

const API_KEY = 'your_api_key';
const ACCOUNT_ID = 'your_account_id';

const params = new URLSearchParams({
  filter_device_type: 'sip_device',
  filter_enabled: 'true'
});

const response = await fetch(
  `https://api.audian.com:8443/v2/accounts/${ACCOUNT_ID}/devices?${params}`,
  {
    headers: { 'X-Auth-Token': API_KEY }
  }
);

const data = await response.json();
console.log(`Found ${data.data.length} SIP devices`);

Combining Filters with Pagination

# Get first 25 enabled users
GET /accounts/{ACCOUNT_ID}/users?filter_status=enabled&page_size=25

# Get next page
GET /accounts/{ACCOUNT_ID}/users?filter_status=enabled&page_size=25&start_key={NEXT_KEY}

Best Practices

Do's ✓

• Use filters to narrow results before fetching
• Combine filters for precision
• Always include page_size with large datasets
• Use date ranges for CDR queries

Don'ts ✗

• Don't fetch all data then filter client-side
• Don't use extremely broad date ranges
• Don't ignore pagination metadata

Troubleshooting

Empty Results

If you get empty results:

• Verify filter parameter names are correct
• Check that filter values match expected formats
• Try removing filters to confirm data exists

Invalid Filter

{
  "data": {
    "message": "invalid filter"
  },
  "error": "400"
}

Solution: Check the filter parameter name and value format.

Next Steps

• Sorting - Sort filtered results
• Pagination - Handle large result sets
• Response Format - Understanding responses