Tickets API reference

Base endpoint

GET /v1/tickets

All endpoints live under /v1. Use the bearer token generated through the Authentication overview guide.

List tickets

GET /v1/tickets?brand_id=...&status=open

Query parameters:

Response snippet:

{
  "data": [
    {
      "id": "tick_01hd...",
      "subject": "Shipping delay",
      "status": "open",
      "brand_id": "brand_123",
      "priority": "high",
      "created_at": "2025-10-04T18:32:11Z"
    }
  ],
  "next_cursor": "eyJwYWdlIjo..."
}

Retrieve a ticket

GET /v1/tickets/{ticket_id}

Returns full conversation history, participants, and audit trail.

Create a ticket

POST /v1/tickets

Body:

{
  "brand_id": "brand_123",
  "subject": "Refund request",
  "description": "Customer requested refund on order 10021",
  "customer": {
    "email": "customer@example.com",
    "name": "Casey Customer"
  }
}

Optional fields include priority, tags, origin (email, web, api), and metadata (arbitrary JSON object limited to 4 KB).

Response returns the created ticket plus queue placement.

Update a ticket

PATCH /v1/tickets/{ticket_id}

Supported fields:

• status
• priority
• assigned_to
• tags

Partial updates are allowed. Include only the fields you want to change.

Post a reply

POST /v1/tickets/{ticket_id}/messages

Body:

{
  "author_type": "agent",
  "body": "Thanks for reaching out! We've refunded the order.",
  "cc": ["finance@example.com"]
}

Use author_type: "customer" when importing historic email threads.

Attachments

1. Request an upload URL: POST /v1/attachments with the file name and content type.
2. Upload the file to the returned URL using PUT.
3. Add the attachment ID to the message payload.

Search tickets

POST /v1/tickets/search

Body:

{
  "query": "refund",
  "filters": {
    "brand_id": "brand_123",
    "created_after": "2025-09-01"
  }
}

The search API uses a hybrid semantic + keyword index. Results include a relevance score.

Webhook events

Subscribe to ticket lifecycle events via the Webhooks dashboard. See the Webhook events summary for payload formats.