Filtering & Search¶

This guide explains how to filter and search for resources in the TopTickets API.

Tickets Filtering¶

The tickets endpoint supports extensive filtering options.

Filter Parameters¶

Parameter	Type	Description	Example
`status`	enum	Filter by ticket status	`open`, `resolved`
`priority`	enum	Filter by priority	`high`, `urgent`
`assigned_user_id`	UUID	Filter by assigned agent	`123e4567-...`
`assigned_team_id`	UUID	Filter by assigned team	`550e8400-...`
`customer_id`	UUID	Filter by customer	`a1b2c3d4-...`
`category`	string	Filter by category	`Technical`
`unassigned`	boolean	Filter unassigned tickets	`true`
`search`	string	Full-text search	`login error`

Status Values¶

new - Newly created, not yet opened
open - Being worked on
pending - Waiting for customer response
resolved - Issue resolved
closed - Ticket closed

Priority Values¶

low - Low priority
medium - Normal priority
high - High priority
urgent - Urgent, needs immediate attention

Filter Examples¶

By Status¶

# Get all open tickets
curl "https://api.toptickets.app/v1/tickets?status=open" \
  -H "Authorization: Bearer YOUR_API_KEY"

response = requests.get(
    f"{BASE_URL}/tickets",
    headers=HEADERS,
    params={"status": "open"}
)

By Priority¶

# Get high priority tickets
curl "https://api.toptickets.app/v1/tickets?priority=high" \
  -H "Authorization: Bearer YOUR_API_KEY"

response = requests.get(
    f"{BASE_URL}/tickets",
    headers=HEADERS,
    params={"priority": "high"}
)

By Assigned Agent¶

# Get tickets assigned to a specific agent
curl "https://api.toptickets.app/v1/tickets?assigned_user_id=123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer YOUR_API_KEY"

response = requests.get(
    f"{BASE_URL}/tickets",
    headers=HEADERS,
    params={"assigned_user_id": "123e4567-e89b-12d3-a456-426614174000"}
)

By Assigned Team¶

# Get tickets assigned to a specific team
curl "https://api.toptickets.app/v1/tickets?assigned_team_id=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY"

Unassigned Tickets¶

# Get tickets with no agent or team assigned
curl "https://api.toptickets.app/v1/tickets?unassigned=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

response = requests.get(
    f"{BASE_URL}/tickets",
    headers=HEADERS,
    params={"unassigned": True}
)

By Category¶

# Get tickets in the Technical category
curl "https://api.toptickets.app/v1/tickets?category=Technical" \
  -H "Authorization: Bearer YOUR_API_KEY"

By Customer¶

# Get all tickets from a specific customer
curl "https://api.toptickets.app/v1/tickets?customer_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer YOUR_API_KEY"

Combining Filters¶

Multiple filters can be combined. All conditions must be met (AND logic):

# Get open, high priority tickets assigned to a specific team
curl "https://api.toptickets.app/v1/tickets?status=open&priority=high&assigned_team_id=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY"

response = requests.get(
    f"{BASE_URL}/tickets",
    headers=HEADERS,
    params={
        "status": "open",
        "priority": "high",
        "assigned_team_id": "550e8400-e29b-41d4-a716-446655440000"
    }
)

Full-Text Search¶

The search parameter performs full-text search across multiple fields.

Searchable Fields¶

For tickets, search looks in:

Subject
Description
Ticket number (e.g., "1042")
Customer name
Customer email

Search Examples¶

# Search for tickets mentioning "login"
curl "https://api.toptickets.app/v1/tickets?search=login" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Search by ticket number
curl "https://api.toptickets.app/v1/tickets?search=1042" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Search by customer email
curl "https://api.toptickets.app/v1/tickets?search=john@example.com" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Search for "password reset"
response = requests.get(
    f"{BASE_URL}/tickets",
    headers=HEADERS,
    params={"search": "password reset"}
)

Combining Search with Filters¶

Search can be combined with other filters:

# Search for "login" in open, high priority tickets
curl "https://api.toptickets.app/v1/tickets?search=login&status=open&priority=high" \
  -H "Authorization: Bearer YOUR_API_KEY"

response = requests.get(
    f"{BASE_URL}/tickets",
    headers=HEADERS,
    params={
        "search": "login",
        "status": "open",
        "priority": "high"
    }
)

Unified Search Endpoint¶

For searching across multiple resource types, use the unified search endpoint:

GET /v1/search?q=search_term

Parameters¶

Parameter	Type	Required	Description
`q`	string	Yes	Search query (min 2 characters)
`limit`	integer	No	Max results per type (1-20, default 5)

Example¶

curl "https://api.toptickets.app/v1/search?q=john&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

response = requests.get(
    f"{BASE_URL}/search",
    headers=HEADERS,
    params={"q": "john", "limit": 5}
)

Response¶

Returns grouped results by resource type:

{
  "tickets": [
    {"id": "...", "subject": "John's login issue", ...}
  ],
  "customers": [
    {"id": "...", "name": "John Doe", "email": "john@example.com", ...}
  ]
}

Best Practices¶

1. Use Specific Filters First¶

Filtering is more efficient than searching. Use filters when you know exactly what you're looking for:

# Good: specific filter
params = {"status": "open", "priority": "urgent"}

# Less efficient: searching then filtering client-side
params = {"search": "urgent"}

2. Limit Results¶

Always use reasonable limits, especially with broad searches:

params = {"search": "error", "limit": 25}

3. URL Encode Search Terms¶

When using special characters, ensure proper URL encoding:

import urllib.parse

search_term = "login & password"
encoded = urllib.parse.quote(search_term)
# Result: "login%20%26%20password"

4. Case Sensitivity¶

Search is case-insensitive:

# These return the same results
params = {"search": "Login"}
params = {"search": "login"}
params = {"search": "LOGIN"}

5. Combine with Pagination¶

For large result sets, combine filtering/search with pagination:

params = {
    "status": "open",
    "search": "error",
    "offset": 0,
    "limit": 50
}