Skip to main content

​
Endpoint

POST /api/v1/tickets

​
Authentication

Requires authentication with ticket:write permission.

​
Request Body

{
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "PENDING",
  "category": "MAINTENANCE",
  "title": "Elevator Malfunction - Floor 3",
  "description": "Elevator not working on floor 3. Residents cannot access upper floors.",
  "attachments": ["https://example.com/image1.jpg"],
  "notes": "Urgent issue reported by multiple residents"
}

​
Body Parameters

ParameterTypeRequiredDescription
userIdstring (UUID)YesID of the user creating the ticket
statusstringNoInitial status (default: PENDING)
categorystringYesTicket category (see valid values below)
titlestringNoShort title/summary (max 120 chars, default: “Untitled”)
descriptionstringYesDetailed description of the issue
attachmentsstring[]NoArray of attachment URLs
notesstringNoInitial notes/comments about the ticket

​
Valid Categories

  • MAINTENANCE - Building maintenance and repairs
  • SECURITY - Security-related issues and concerns
  • CLEANING - Cleaning and sanitation requests
  • WASTE - Waste management and disposal
  • ELECTRICITY - Electrical issues and repairs
  • WATER - Water supply and plumbing issues
  • GAS - Gas supply and safety concerns
  • INTERNET - Internet connectivity and IT issues
  • OTHER - Miscellaneous requests

​
Request Example

curl -X POST "http://localhost:3001/api/v1/tickets" \
  -H "Content-Type: application/json" \
  -H "Cookie: session=your-session-cookie" \
  -d '{
    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "PENDING",
    "category": "MAINTENANCE",
    "title": "Elevator Malfunction - Floor 3",
    "description": "Elevator not working on floor 3. Residents cannot access upper floors.",
    "attachments": ["https://example.com/image1.jpg"],
    "notes": "Urgent issue reported by multiple residents"
  }'

​
Response

​
Success Response (201)

{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "PENDING",
  "category": "MAINTENANCE",
  "title": "Elevator Malfunction - Floor 3",
  "description": "Elevator not working on floor 3. Residents cannot access upper floors.",
  "attachments": ["https://example.com/image1.jpg"],
  "assignedTo": null,
  "notes": "Urgent issue reported by multiple residents",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

​
Error Response (400)

{
  "success": false,
  "error": {
    "message": "Validation failed",
    "code": "VALIDATION_ERROR",
    "details": {
      "userId": "User ID is required",
      "category": "Invalid category value"
    }
  }
}

​
Error Response (401)

{
  "success": false,
  "error": {
    "message": "Unauthorized access",
    "code": "UNAUTHORIZED"
  }
}

​
Error Response (403)

{
  "success": false,
  "error": {
    "message": "Insufficient permissions",
    "code": "FORBIDDEN"
  }
}

​
Error Response (404)

{
  "success": false,
  "error": {
    "message": "User not found",
    "code": "NOT_FOUND"
  }
}

​
Notes

  • New tickets are created with PENDING status by default unless specified
  • The title field defaults to “Untitled” if not provided (max 120 characters)
  • The assignedTo field is initially null
  • Both createdAt and updatedAt timestamps are set to the current time
  • The userId must reference a valid user in the system
  • The notes field is a single text string, not an array
  • Attachment URLs should be valid and accessible
  • Use the Assign Ticket endpoint to assign the ticket to a technician