Tickets API

Manage support tickets via the API.

Endpoints

Method	Endpoint	Description
GET	/tickets	List tickets
POST	/tickets	Create ticket
GET	/tickets/:id	Get ticket
PATCH	/tickets/:id	Update ticket
DELETE	/tickets/:id	Delete ticket

List Tickets

GET /api/v1/tickets

Query Parameters

Parameter	Type	Description
status	string	Filter by status: open, pending, resolved, closed
priority	string	Filter by priority: low, normal, high, urgent
assignee_id	uuid	Filter by assignee
contact_id	uuid	Filter by contact
company_id	uuid	Filter by company
label_ids	uuid[]	Filter by labels (comma-separated)
search	string	Search subject and messages
created_after	datetime	Tickets created after date
created_before	datetime	Tickets created before date
page	integer	Page number (default: 1)
per_page	integer	Items per page (default: 20, max: 100)

Response

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "code": "ACME-42",
      "subject": "Cannot login to dashboard",
      "status": "open",
      "priority": "high",
      "contact": {
        "id": "...",
        "name": "John Doe",
        "email": "john@example.com"
      },
      "company": {
        "id": "...",
        "name": "Acme Corp"
      },
      "assignee": {
        "id": "...",
        "name": "Jane Agent"
      },
      "labels": [
        { "id": "...", "name": "Technical", "color": "#3B82F6" }
      ],
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T14:22:00Z"
    }
  ],
  "meta": {
    "total": 156,
    "page": 1,
    "per_page": 20
  }
}

Create Ticket

POST /api/v1/tickets

Request Body

{
  "subject": "Cannot login to dashboard",
  "description": "User reports being unable to login since this morning...",
  "contact_id": "contact-uuid",
  "priority": "high",
  "assignee_id": "user-uuid",
  "label_ids": ["label-uuid-1", "label-uuid-2"]
}

Field	Type	Required	Description
subject	string	Yes	Ticket subject
description	string	No	Initial message body
contact_id	uuid	Yes	Contact who submitted
priority	string	No	low, normal, high, urgent (default: normal)
assignee_id	uuid	No	User to assign
label_ids	uuid[]	No	Labels to apply

Response

{
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "code": "ACME-43",
    "subject": "Cannot login to dashboard",
    "status": "open",
    "priority": "high",
    ...
  }
}

Get Ticket

GET /api/v1/tickets/:id

Response

Full ticket object including messages and time entries:

{
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "code": "ACME-42",
    "subject": "Cannot login to dashboard",
    "status": "open",
    "priority": "high",
    "contact": { ... },
    "company": { ... },
    "assignee": { ... },
    "labels": [ ... ],
    "messages": [
      {
        "id": "...",
        "body": "I can't login since this morning...",
        "is_internal": false,
        "sender": { "name": "John Doe", "email": "john@example.com" },
        "created_at": "2024-01-15T10:30:00Z"
      }
    ],
    "time_entries": [
      {
        "id": "...",
        "duration_minutes": 30,
        "description": "Investigated login issue",
        "billable": true,
        "user": { "name": "Jane Agent" },
        "created_at": "2024-01-15T11:00:00Z"
      }
    ],
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T14:22:00Z"
  }
}

Update Ticket

PATCH /api/v1/tickets/:id

Request Body

Only include fields you want to update:

{
  "status": "pending",
  "priority": "normal",
  "assignee_id": "new-user-uuid",
  "label_ids": ["label-uuid-1"]
}

Field	Type	Description
subject	string	Update subject
status	string	Change status
priority	string	Change priority
assignee_id	uuid	Reassign ticket
label_ids	uuid[]	Replace labels

Note

Setting label_ids replaces all labels. To add a label, include all existing label IDs plus the new one.

Response

Updated ticket object.

Delete Ticket

DELETE /api/v1/tickets/:id

Response

204 No Content

Caution

Deleting a ticket also deletes all messages, time entries, and attachments. This cannot be undone.

Label Operations

Add Labels

POST /api/v1/tickets/:id/labels

{
  "label_ids": ["label-uuid-1", "label-uuid-2"]
}

Remove Labels

DELETE /api/v1/tickets/:id/labels

{
  "label_ids": ["label-uuid-1"]
}

Assignment

Assign Ticket

POST /api/v1/tickets/:id/assign

{
  "assignee_id": "user-uuid"
}

Unassign Ticket

POST /api/v1/tickets/:id/unassign

Status Transitions

Tickets follow a workflow. Valid transitions:

From	To
open	pending, resolved, closed
pending	open, resolved, closed
resolved	open, closed
closed	open

Error Codes

Code	Description
TICKET_NOT_FOUND	Ticket doesn’t exist
CONTACT_NOT_FOUND	Contact ID doesn’t exist
INVALID_STATUS	Invalid status value
INVALID_PRIORITY	Invalid priority value
LABEL_NOT_FOUND	One or more label IDs don’t exist