Quickstart¶

Get started with the TopTickets API in 5 minutes. This guide shows you how to make your first API request.

Prerequisites¶

• An API key (see API Keys for how to create one)
• A tool to make HTTP requests (cURL, Python, or any HTTP client)

Step 1: Get Your API Key¶

You'll need an API key to authenticate your requests. If you don't have one yet, create one through the TopTickets dashboard or via the API Keys endpoint.

Your API key will look like this:

tt_admin_a1b2c3d4e5f6g7h8i9j0...

Step 2: Make Your First Request¶

Let's verify your API key works by listing tickets.

curl -X GET "https://api.toptickets.app/v1/tickets" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.toptickets.app/v1"

response = requests.get(
    f"{BASE_URL}/tickets",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    }
)

print(response.json())

You should receive a response like:

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "ticket_number": 1042,
    "tracking_token": "a3d5f8e9-1b2c-4d5e-8f9a-1b2c3d4e5f6a",
    "ticket_display_id": "TKT-1042"
  }
]

Step 3: Create a Ticket¶

Now let's create a new support ticket.

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 saying invalid credentials.",
    "priority": "high"
  }'

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.toptickets.app/v1"

ticket_data = {
    "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 saying invalid credentials.",
    "priority": "high"
}

response = requests.post(
    f"{BASE_URL}/tickets",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    },
    json=ticket_data
)

print(response.json())

Response:

{
  "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 saying invalid credentials.",
  "status": "new",
  "priority": "high",
  "category": null,
  "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
}

Step 4: Get Ticket Details¶

Retrieve the full details of a specific ticket using its ID.

curl -X GET "https://api.toptickets.app/v1/tickets/123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.toptickets.app/v1"
TICKET_ID = "123e4567-e89b-12d3-a456-426614174000"

response = requests.get(
    f"{BASE_URL}/tickets/{TICKET_ID}",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    }
)

print(response.json())

Next Steps¶

Now that you've made your first API requests, explore more features:

• Authentication - Learn about scopes and permissions
• API Keys - Create and manage API keys
• Tickets API - Full ticket operations
• Error Handling - Handle errors gracefully

Common Issues¶

401 Unauthorized¶

Your API key may be invalid, expired, or revoked. Check that:

• The key is correctly formatted (starts with tt_)
• The key hasn't expired
• The key hasn't been revoked

403 Forbidden¶

Your API key doesn't have the required scope for this operation. Check API Scopes to see which scopes are required.

429 Too Many Requests¶

You've exceeded the rate limit. Wait a moment and retry. See Rate Limits for details.