Skip to content

Ticket API Documentation

Overview

The Kindly API ticket system provides a comprehensive ticketing solution for customer support. All ticket endpoints require authentication via Bearer token.

Authentication

All ticket endpoints require a valid JWT token in the Authorization header: 

Authorization: Bearer <your-jwt-token>

Endpoints

List Tickets

Get a paginated list of tickets for the authenticated user.

Endpoint: GET /api/tickets

Query Parameters: - page (optional): Page number (default: 1) - limit (optional): Items per page (default: 20, max: 100)

Response: 

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "ticket_number": 1001,
      "title": "Cannot login to account",
      "description": "User is experiencing login issues...",
      "status": "open",
      "priority": "high",
      "customer_email": "customer@example.com",
      "customer_name": "John Doe",
      "tags": ["login", "urgent"],
      "created_at": "2024-01-20T10:00:00Z",
      "updated_at": "2024-01-20T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45,
    "pages": 3,
    "has_next": true,
    "has_prev": false
  }
}

Create Ticket

Create a new support ticket.

Endpoint: POST /api/tickets

Request Body: 

{
  "title": "Cannot login to account",
  "description": "User is experiencing login issues when trying to access the dashboard",
  "customer_email": "customer@example.com",
  "customer_name": "John Doe",
  "priority": "high",
  "tags": ["login", "urgent"]
}

Validation Rules: - title: Required, 1-255 characters - description: Required, 1-10000 characters - customer_email: Required, valid email format - customer_name: Optional, max 255 characters - priority: Optional, one of: "low", "normal", "high", "urgent" (default: "normal") - tags: Optional, array of strings

Response: 201 Created 

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "ticket_number": 1001,
  "title": "Cannot login to account",
  "description": "User is experiencing login issues...",
  "status": "open",
  "priority": "high",
  "customer_email": "customer@example.com",
  "customer_name": "John Doe",
  "tags": ["login", "urgent"],
  "created_at": "2024-01-20T10:00:00Z",
  "updated_at": "2024-01-20T10:00:00Z"
}

Get Ticket

Retrieve a specific ticket by ID.

Endpoint: GET /api/tickets/:ticket_id

Response: 

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "ticket_number": 1001,
  "title": "Cannot login to account",
  "description": "User is experiencing login issues...",
  "status": "open",
  "priority": "high",
  "customer_email": "customer@example.com",
  "customer_name": "John Doe",
  "tags": ["login", "urgent"],
  "created_at": "2024-01-20T10:00:00Z",
  "updated_at": "2024-01-20T10:00:00Z"
}

Update Ticket

Update an existing ticket. All fields are optional.

Endpoint: PUT /api/tickets/:ticket_id

Request Body: 

{
  "title": "Updated title",
  "status": "in_progress",
  "priority": "urgent",
  "assigned_to": "550e8400-e29b-41d4-a716-446655440001",
  "tags": ["updated", "in-progress"]
}

Validation Rules: - status: Optional, one of: "open", "in_progress", "resolved", "closed" - priority: Optional, one of: "low", "normal", "high", "urgent" - All other fields follow the same rules as create

Response: 

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "ticket_number": 1001,
  "title": "Updated title",
  "description": "User is experiencing login issues...",
  "status": "in_progress",
  "priority": "urgent",
  "customer_email": "customer@example.com",
  "customer_name": "John Doe",
  "tags": ["updated", "in-progress"],
  "created_at": "2024-01-20T10:00:00Z",
  "updated_at": "2024-01-20T11:00:00Z"
}

Delete Ticket

Soft delete a ticket (sets status to "deleted").

Endpoint: DELETE /api/tickets/:ticket_id

Response: 204 No Content

Error Responses

All endpoints may return the following error responses:

400 Bad Request

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "timestamp": "2024-01-20T10:00:00Z"
  }
}

401 Unauthorized

{
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "Invalid or missing authentication token",
    "timestamp": "2024-01-20T10:00:00Z"
  }
}

404 Not Found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Ticket not found",
    "timestamp": "2024-01-20T10:00:00Z"
  }
}

500 Internal Server Error

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error",
    "timestamp": "2024-01-20T10:00:00Z"
  }
}

Security Considerations

  1. Authorization: Users can only access their own tickets. The system uses the authenticated user's ID from the JWT token to filter tickets.

  2. Soft Deletes: Tickets are never hard deleted. The delete endpoint sets the status to "deleted" but keeps the record for audit purposes.

  3. Ticket Numbers: Each user has their own sequence of ticket numbers starting from 1.

  4. Rate Limiting: All ticket endpoints are subject to rate limiting to prevent abuse.

Best Practices

  1. Pagination: Always use pagination when listing tickets to improve performance.

  2. Tags: Use consistent tag naming conventions to make searching and filtering easier.

  3. Priority Levels:

  4. low: Non-urgent issues
  5. normal: Standard support requests
  6. high: Important issues affecting user experience

  7. urgent: Critical issues requiring immediate attention

  8. Status Workflow:

  9. open: New tickets
  10. in_progress: Being worked on
  11. resolved: Solution provided, awaiting confirmation
  12. closed: Ticket completed
  13. deleted: Soft deleted tickets