Ticket Management¶

This example demonstrates common ticket management workflows including listing, filtering, updating, and bulk operations.

Overview¶

We'll cover:

Listing and filtering tickets
Building a ticket dashboard
Bulk status updates
Assigning tickets to agents
Working with ticket queues

Setup¶

import requests
from datetime import datetime, timedelta

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.toptickets.app/v1"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

Listing and Filtering Tickets¶

Get All Open Tickets¶

PythoncURL

def get_open_tickets():
    """Get all open tickets."""
    response = requests.get(
        f"{BASE_URL}/tickets",
        headers=HEADERS,
        params={"status": "open", "limit": 100}
    )
    return response.json()

open_tickets = get_open_tickets()
print(f"Found {len(open_tickets)} open tickets")

curl "https://api.toptickets.app/v1/tickets?status=open&limit=100" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get High Priority Unassigned Tickets¶

def get_urgent_unassigned():
    """Get tickets that need immediate attention."""
    response = requests.get(
        f"{BASE_URL}/tickets",
        headers=HEADERS,
        params={
            "status": "open",
            "priority": "urgent",
            "unassigned": True
        }
    )
    return response.json()

urgent = get_urgent_unassigned()
print(f"Found {len(urgent)} urgent unassigned tickets")

Get Tickets for a Specific Team¶

def get_team_tickets(team_id):
    """Get all tickets assigned to a team."""
    response = requests.get(
        f"{BASE_URL}/tickets",
        headers=HEADERS,
        params={
            "assigned_team_id": team_id,
            "status": "open"
        }
    )
    return response.json()

TECH_SUPPORT_TEAM = "550e8400-e29b-41d4-a716-446655440000"
team_tickets = get_team_tickets(TECH_SUPPORT_TEAM)

Building a Ticket Dashboard¶

Dashboard Statistics¶

Fetch data for a support dashboard:

def get_dashboard_data():
    """Gather statistics for a support dashboard."""
    dashboard = {}

    # Open tickets by priority
    for priority in ["urgent", "high", "medium", "low"]:
        response = requests.get(
            f"{BASE_URL}/tickets",
            headers=HEADERS,
            params={"status": "open", "priority": priority, "limit": 1}
        )
        # Note: This is simplified - you'd use the actual count endpoint
        dashboard[f"open_{priority}"] = len(response.json())

    # Unassigned tickets
    response = requests.get(
        f"{BASE_URL}/tickets",
        headers=HEADERS,
        params={"unassigned": True, "status": "open"}
    )
    dashboard["unassigned"] = len(response.json())

    return dashboard

stats = get_dashboard_data()
print(f"Urgent tickets: {stats.get('open_urgent', 0)}")
print(f"Unassigned: {stats.get('unassigned', 0)}")

Agent Workload View¶

def get_agent_workload(agent_ids):
    """Get ticket counts per agent."""
    workload = {}

    for agent_id in agent_ids:
        response = requests.get(
            f"{BASE_URL}/tickets",
            headers=HEADERS,
            params={
                "assigned_user_id": agent_id,
                "status": "open"
            }
        )
        workload[agent_id] = len(response.json())

    return workload

agents = ["agent-uuid-1", "agent-uuid-2", "agent-uuid-3"]
workload = get_agent_workload(agents)

Bulk Operations¶

Update Multiple Tickets¶

def bulk_update_tickets(ticket_ids, update_data):
    """Update multiple tickets with the same data."""
    results = {"success": [], "failed": []}

    for ticket_id in ticket_ids:
        try:
            response = requests.patch(
                f"{BASE_URL}/tickets/{ticket_id}",
                headers=HEADERS,
                json=update_data
            )
            response.raise_for_status()
            results["success"].append(ticket_id)
        except requests.exceptions.HTTPError as e:
            results["failed"].append({
                "id": ticket_id,
                "error": str(e)
            })

    return results

# Close multiple resolved tickets
ticket_ids = ["uuid-1", "uuid-2", "uuid-3"]
results = bulk_update_tickets(ticket_ids, {"status": "closed"})
print(f"Closed {len(results['success'])} tickets")

Assign Tickets to a Team¶

def assign_unassigned_to_team(team_id, limit=10):
    """Assign unassigned tickets to a team."""
    # Get unassigned tickets
    response = requests.get(
        f"{BASE_URL}/tickets",
        headers=HEADERS,
        params={"unassigned": True, "status": "open", "limit": limit}
    )
    tickets = response.json()

    assigned = []
    for ticket in tickets:
        response = requests.patch(
            f"{BASE_URL}/tickets/{ticket['id']}",
            headers=HEADERS,
            json={"assigned_team_id": team_id}
        )
        if response.ok:
            assigned.append(ticket["id"])

    return assigned

# Assign to Technical Support team
assigned = assign_unassigned_to_team(TECH_SUPPORT_TEAM)
print(f"Assigned {len(assigned)} tickets to team")

Working with Ticket Queues¶

Round-Robin Assignment¶

Distribute tickets evenly among agents:

def round_robin_assign(ticket_ids, agent_ids):
    """Assign tickets using round-robin."""
    assignments = []
    agent_count = len(agent_ids)

    for i, ticket_id in enumerate(ticket_ids):
        agent_id = agent_ids[i % agent_count]

        response = requests.patch(
            f"{BASE_URL}/tickets/{ticket_id}",
            headers=HEADERS,
            json={"assigned_user_id": agent_id}
        )

        if response.ok:
            assignments.append({
                "ticket": ticket_id,
                "agent": agent_id
            })

    return assignments

# Get unassigned tickets and distribute
unassigned = requests.get(
    f"{BASE_URL}/tickets",
    headers=HEADERS,
    params={"unassigned": True, "limit": 30}
).json()

agents = ["agent-1-uuid", "agent-2-uuid", "agent-3-uuid"]
assignments = round_robin_assign(
    [t["id"] for t in unassigned],
    agents
)

Priority-Based Queue Processing¶

Process tickets by priority:

def process_ticket_queue():
    """Process tickets in priority order."""
    priority_order = ["urgent", "high", "medium", "low"]

    for priority in priority_order:
        tickets = requests.get(
            f"{BASE_URL}/tickets",
            headers=HEADERS,
            params={
                "priority": priority,
                "status": "new",
                "limit": 10
            }
        ).json()

        for ticket in tickets:
            # Mark as being worked on
            requests.patch(
                f"{BASE_URL}/tickets/{ticket['id']}",
                headers=HEADERS,
                json={"status": "open"}
            )

            # Process the ticket...
            print(f"Processing {ticket['ticket_display_id']} ({priority})")

        if tickets:
            break  # Process highest priority first

Complete Example: Ticket Triage Script¶

A complete script for triaging new tickets:

import requests
from datetime import datetime

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.toptickets.app/v1"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Team and category mappings
TEAM_MAPPING = {
    "Technical": "tech-team-uuid",
    "Billing": "billing-team-uuid",
    "Sales": "sales-team-uuid"
}

DEFAULT_TEAM = "general-support-uuid"

def triage_new_tickets():
    """Triage all new tickets by assigning to appropriate teams."""
    # Get new tickets
    response = requests.get(
        f"{BASE_URL}/tickets",
        headers=HEADERS,
        params={"status": "new", "limit": 100}
    )
    new_tickets = response.json()

    print(f"Found {len(new_tickets)} new tickets to triage")

    triaged = []
    for ticket in new_tickets:
        # Determine team based on category
        category = ticket.get("category", "")
        team_id = TEAM_MAPPING.get(category, DEFAULT_TEAM)

        # Update ticket
        update_data = {
            "status": "open",
            "assigned_team_id": team_id
        }

        # Escalate urgent tickets
        if ticket.get("priority") == "urgent":
            update_data["assigned_user_id"] = "senior-agent-uuid"

        response = requests.patch(
            f"{BASE_URL}/tickets/{ticket['id']}",
            headers=HEADERS,
            json=update_data
        )

        if response.ok:
            triaged.append({
                "ticket": ticket["ticket_display_id"],
                "team": team_id,
                "priority": ticket.get("priority")
            })

            # Add triage note
            requests.post(
                f"{BASE_URL}/tickets/{ticket['id']}/comments",
                headers=HEADERS,
                json={
                    "content": f"Auto-triaged to {category or 'General'} team",
                    "is_internal": True
                }
            )

    return triaged

def print_summary(triaged):
    """Print triage summary."""
    print("\nTriage Summary")
    print("-" * 40)
    print(f"Total triaged: {len(triaged)}")

    by_team = {}
    for t in triaged:
        team = t["team"]
        by_team[team] = by_team.get(team, 0) + 1

    for team, count in by_team.items():
        print(f"  {team}: {count} tickets")

if __name__ == "__main__":
    triaged = triage_new_tickets()
    print_summary(triaged)

Searching for Tickets¶

def find_related_tickets(search_term):
    """Search for tickets matching a term."""
    response = requests.get(
        f"{BASE_URL}/tickets",
        headers=HEADERS,
        params={"search": search_term, "limit": 20}
    )
    return response.json()

# Find tickets about login issues
login_tickets = find_related_tickets("login error")
print(f"Found {len(login_tickets)} related tickets")

Get Customer's Ticket History¶

def get_customer_history(customer_id):
    """Get all tickets for a customer."""
    response = requests.get(
        f"{BASE_URL}/tickets",
        headers=HEADERS,
        params={"customer_id": customer_id, "limit": 50}
    )
    tickets = response.json()

    # Group by status
    by_status = {}
    for ticket in tickets:
        status = ticket.get("status", "unknown")
        by_status.setdefault(status, []).append(ticket)

    return by_status

history = get_customer_history("customer-uuid")
print(f"Open: {len(history.get('open', []))}")
print(f"Resolved: {len(history.get('resolved', []))}")

Next Steps¶

Create Ticket Flow - Creating tickets with full context
API Reference: Tickets - Full endpoint documentation
Filtering & Search - Advanced filtering techniques