Skip to content

Tickets

Tickets are the core resource for managing customer support requests. Each ticket contains customer information, the issue description, status, priority, and can have comments and attachments.

Endpoints

Method Endpoint Description Scope Required
GET /v1/tickets List tickets tickets:read
GET /v1/tickets/{id} Get ticket tickets:read
POST /v1/tickets Create ticket tickets:write
PATCH /v1/tickets/{id} Update ticket tickets:write
DELETE /v1/tickets/{id} Delete ticket tickets:delete

The Ticket Object

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "ticket_number": 1042,
  "tracking_token": "a3d5f8e9-1b2c-4d5e-8f9a-1b2c3d4e5f6a",
  "ticket_display_id": "TKT-1042",
  "customer_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "subject": "Unable to login to my account",
  "description": "When I try to login, I get an error...",
  "status": "open",
  "priority": "high",
  "category": "Technical",
  "assigned_user_id": "123e4567-e89b-12d3-a456-426614174000",
  "assigned_team_id": "550e8400-e29b-41d4-a716-446655440000",
  "due_date": "2025-01-20T17:00:00Z",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-16T14:22:00Z",
  "resolved_at": null,
  "closed_at": null
}

Attributes

Field Type Description
id UUID Unique ticket identifier
ticket_number integer Sequential human-readable number
tracking_token UUID Token for customer self-service access
ticket_display_id string Formatted ID (e.g., "TKT-1042")
customer_id UUID ID of the associated customer
subject string Brief summary of the issue
description string Detailed description
status enum new, open, pending, resolved, closed
priority enum low, medium, high, urgent
category string Category for organization
assigned_user_id UUID ID of assigned agent (nullable)
assigned_team_id UUID ID of assigned team (nullable)
due_date datetime Target resolution date (nullable)
created_at datetime Creation timestamp
updated_at datetime Last modification timestamp
resolved_at datetime When marked resolved (nullable)
closed_at datetime When closed (nullable)

List Tickets

Retrieve a list of tickets with optional filtering and search.

GET /v1/tickets

Query Parameters

Parameter Type Description
status enum Filter by status
priority enum Filter by priority
assigned_user_id UUID Filter by assigned agent
assigned_team_id UUID Filter by assigned team
customer_id UUID Filter by customer
category string Filter by category
unassigned boolean Filter for unassigned tickets
search string Search subject, description, ticket number, customer
limit integer Max results (default: 100, max: 500)
offset integer Skip results (default: 0)

Examples

# List all tickets
curl -X GET "https://api.toptickets.app/v1/tickets" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Filter by status and priority
curl -X GET "https://api.toptickets.app/v1/tickets?status=open&priority=high" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Search tickets
curl -X GET "https://api.toptickets.app/v1/tickets?search=login%20error" \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

# List all tickets
response = requests.get(
    "https://api.toptickets.app/v1/tickets",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

# Filter by status and priority
response = requests.get(
    "https://api.toptickets.app/v1/tickets",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={"status": "open", "priority": "high"}
)

# Search tickets
response = requests.get(
    "https://api.toptickets.app/v1/tickets",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={"search": "login error"}
)

Response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "ticket_number": 1042,
    "tracking_token": "a3d5f8e9-1b2c-4d5e-8f9a-1b2c3d4e5f6a",
    "ticket_display_id": "TKT-1042"
  },
  {
    "id": "661f9511-f30c-52e5-b827-557766551111",
    "ticket_number": 1043,
    "tracking_token": "b5f7g0b1-3d4e-6f7g-0b1c-3d4e5f6g7h8i",
    "ticket_display_id": "TKT-1043"
  }
]

Get Ticket

Retrieve a single ticket by ID.

GET /v1/tickets/{ticket_id}

Path Parameters

Parameter Type Description
ticket_id UUID The ticket ID

Examples

curl -X GET "https://api.toptickets.app/v1/tickets/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

TICKET_ID = "550e8400-e29b-41d4-a716-446655440000"

response = requests.get(
    f"https://api.toptickets.app/v1/tickets/{TICKET_ID}",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "ticket_number": 1042,
  "tracking_token": "a3d5f8e9-1b2c-4d5e-8f9a-1b2c3d4e5f6a",
  "ticket_display_id": "TKT-1042",
  "customer_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "subject": "Unable to login to my account",
  "description": "When I try to login, I get an error saying 'Invalid credentials'.",
  "status": "open",
  "priority": "high",
  "category": "Technical",
  "assigned_user_id": null,
  "assigned_team_id": null,
  "due_date": null,
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z",
  "resolved_at": null,
  "closed_at": null
}

Create Ticket

Create a new support ticket.

POST /v1/tickets

Request Body

Field Type Required Description
customer_name string Yes Customer's full name
customer_email string Yes Customer's email address
subject string Yes Brief summary (max 500 chars)
description string Yes Detailed description
priority enum No low, medium (default), high, urgent
category string No Category (max 100 chars)
assigned_user_id UUID No Assign to specific agent
assigned_team_id UUID No Assign to specific team

Examples

curl -X POST "https://api.toptickets.app/v1/tickets" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_name": "John Doe",
    "customer_email": "john.doe@example.com",
    "subject": "Unable to login to my account",
    "description": "I have been trying to login but keep getting an error message.",
    "priority": "high",
    "category": "Technical"
  }'

import requests

response = requests.post(
    "https://api.toptickets.app/v1/tickets",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "customer_name": "John Doe",
        "customer_email": "john.doe@example.com",
        "subject": "Unable to login to my account",
        "description": "I have been trying to login but keep getting an error message.",
        "priority": "high",
        "category": "Technical"
    }
)

Response (201 Created)

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "ticket_number": 1043,
  "tracking_token": "b4e6f9a0-2c3d-5e6f-9a0b-2c3d4e5f6a7b",
  "ticket_display_id": "TKT-1043",
  "customer_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "subject": "Unable to login to my account",
  "description": "I have been trying to login but keep getting an error message.",
  "status": "new",
  "priority": "high",
  "category": "Technical",
  "assigned_user_id": null,
  "assigned_team_id": null,
  "due_date": null,
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z",
  "resolved_at": null,
  "closed_at": null
}

Update Ticket

Update an existing ticket. All fields are optional - only include fields you want to change.

PATCH /v1/tickets/{ticket_id}

Path Parameters

Parameter Type Description
ticket_id UUID The ticket ID

Request Body

Field Type Description
subject string Updated subject
status enum Updated status
priority enum Updated priority
category string Updated category
assigned_user_id UUID Reassign to agent (null to unassign)
assigned_team_id UUID Reassign to team (null to unassign)
due_date datetime Target resolution date

Examples

# Update status and priority
curl -X PATCH "https://api.toptickets.app/v1/tickets/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "resolved",
    "priority": "low"
  }'

# Assign to agent
curl -X PATCH "https://api.toptickets.app/v1/tickets/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assigned_user_id": "123e4567-e89b-12d3-a456-426614174000"
  }'

import requests

TICKET_ID = "550e8400-e29b-41d4-a716-446655440000"

# Update status and priority
response = requests.patch(
    f"https://api.toptickets.app/v1/tickets/{TICKET_ID}",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "status": "resolved",
        "priority": "low"
    }
)

# Assign to agent
response = requests.patch(
    f"https://api.toptickets.app/v1/tickets/{TICKET_ID}",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "assigned_user_id": "123e4567-e89b-12d3-a456-426614174000"
    }
)

Response

Returns the updated ticket object.

Delete Ticket

Permanently delete a ticket.

DELETE /v1/tickets/{ticket_id}

Path Parameters

Parameter Type Description
ticket_id UUID The ticket ID

Examples

curl -X DELETE "https://api.toptickets.app/v1/tickets/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

TICKET_ID = "550e8400-e29b-41d4-a716-446655440000"

response = requests.delete(
    f"https://api.toptickets.app/v1/tickets/{TICKET_ID}",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

if response.status_code == 204:
    print("Ticket deleted")

Response

Returns 204 No Content on success.

Permanent Deletion

This action cannot be undone. All associated comments and attachments will also be deleted.