Events Management API

Author: Josh, Lead Backend Team
Last Updated: 2025-12-11
Version: v1.0

Base URL: https://api.nexgate.com/api/v1

Short Description: The Events Management API provides comprehensive functionality for creating, managing, and publishing events in the Nexgate platform. This API implements a step-by-step draft workflow where users create event drafts, progressively complete required stages (Basic Info, Schedule, Location, Tickets), attach commerce entities (products/shops), and finally publish events. The system includes robust duplicate detection, RSA key generation for ticket security, and support for multiple event formats (In-Person, Online, Hybrid).

Hints:

One Draft at a Time: Users can only have ONE active draft. Must publish or discard before creating a new draft
Stage-Based Workflow: Events progress through required stages: BASIC_INFO → SCHEDULE → LOCATION_DETAILS → TICKETS → (optional: MEDIA, LINKS) → REVIEW
Event Formats: IN_PERSON (requires venue), ONLINE (requires virtual details), HYBRID (requires both)
Event Status Flow: DRAFT → PUBLISHED → HAPPENING → COMPLETED (or CANCELLED)
RSA Keys: Auto-generated on publish for ticket signature verification
Duplicate Detection: Advanced similarity checking (title 40%, date 30%, location 30%) with 85% threshold for public events
Visibility Levels: PUBLIC (discoverable), PRIVATE (invite-only), UNLISTED (link-only)
Commerce Integration: Attach up to 10 products and 5 shops to events
Multi-Day Support: Events can span multiple days with individual schedules per day
Pagination: 1-indexed (page=1), default size=10
Timezone Support: All dates in ISO 8601 with timezone (e.g., 2025-12-15T18:00:00+03:00)

Standard Response Format

All API responses follow a consistent structure using our Globe Response Builder pattern:

Success Response Structure

{
  "success": true,
  "httpStatus": "OK",
  "message": "Operation completed successfully",
  "action_time": "2025-12-11T10:30:45",
  "data": {
    // Actual response data goes here
  }
}

Error Response Structure

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Error description",
  "action_time": "2025-12-11T10:30:45",
  "data": "Error description"
}

HTTP Method Badge Standards

GET - GET - Green (Read operations)
POST - POST - Blue (Create operations)
PATCH - PATCH - Orange (Partial update operations)
DELETE - DELETE - Red (Delete operations)

EventResponse Structure

This is the comprehensive response structure returned by event endpoints:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "East African Tech Summit 2025",
  "slug": "east-african-tech-summit-2025-a1b2c3d4",
  "description": "Annual technology conference bringing together innovators...",
  "category": {
    "categoryId": "660e8400-e29b-41d4-a716-446655440001",
    "categoryName": "Technology & Innovation",
    "categorySlug": "technology-innovation"
  },
  "eventFormat": "HYBRID",
  "eventVisibility": "PUBLIC",
  "status": "PUBLISHED",
  "schedule": {
    "startDateTime": "2025-12-15T08:00:00+03:00",
    "endDateTime": "2025-12-17T18:00:00+03:00",
    "timezone": "Africa/Nairobi",
    "days": [
      {
        "id": "770e8400-e29b-41d4-a716-446655440002",
        "date": "2025-12-15",
        "startTime": "08:00:00",
        "endTime": "18:00:00",
        "description": "Opening day - Keynotes and workshops",
        "dayOrder": 1
      },
      {
        "id": "880e8400-e29b-41d4-a716-446655440003",
        "date": "2025-12-16",
        "startTime": "09:00:00",
        "endTime": "17:00:00",
        "description": "Day 2 - Deep dive sessions",
        "dayOrder": 2
      },
      {
        "id": "990e8400-e29b-41d4-a716-446655440004",
        "date": "2025-12-17",
        "startTime": "09:00:00",
        "endTime": "16:00:00",
        "description": "Final day - Hackathon presentations",
        "dayOrder": 3
      }
    ]
  },
  "venue": {
    "name": "Nairobi Convention Centre",
    "address": "Harambee Avenue, Nairobi, Kenya",
    "coordinates": {
      "latitude": "-1.2921",
      "longitude": "36.8219"
    }
  },
  "virtualDetails": {
    "meetingLink": "https://zoom.us/j/1234567890",
    "meetingId": "123 456 7890",
    "passcode": "TechSummit2025"
  },
  "media": {
    "banner": "https://cdn.nexgate.com/events/summit-banner.jpg",
    "thumbnail": "https://cdn.nexgate.com/events/summit-thumb.jpg",
    "gallery": [
      "https://cdn.nexgate.com/events/gallery1.jpg",
      "https://cdn.nexgate.com/events/gallery2.jpg"
    ]
  },
  "linkedProducts": [
    {
      "productId": "aa0e8400-e29b-41d4-a716-446655440005",
      "productName": "Tech Summit Merch Bundle",
      "productSlug": "tech-summit-merch-bundle"
    }
  ],
  "linkedShops": [
    {
      "shopId": "bb0e8400-e29b-41d4-a716-446655440006",
      "shopName": "Official Event Store",
      "shopSlug": "official-event-store"
    }
  ],
  "tickets": [
    {
      "id": "cc0e8400-e29b-41d4-a716-446655440007",
      "name": "Early Bird",
      "price": 50.00,
      "totalTickets": 100,
      "ticketsSold": 75,
      "ticketsAvailable": 25,
      "isSoldOut": false,
      "attendanceMode": "HYBRID",
      "status": "ON_SALE",
      "isOnSale": true
    },
    {
      "id": "dd0e8400-e29b-41d4-a716-446655440008",
      "name": "Virtual Pass",
      "price": 25.00,
      "totalTickets": 500,
      "ticketsSold": 320,
      "ticketsAvailable": 180,
      "isSoldOut": false,
      "attendanceMode": "ONLINE",
      "status": "ON_SALE",
      "isOnSale": true
    }
  ],
  "organizer": {
    "organizerId": "ee0e8400-e29b-41d4-a716-446655440009",
    "organizerName": "John Doe",
    "organizerUsername": "johndoe"
  },
  "currentStage": "REVIEW",
  "completedStages": ["BASIC_INFO", "SCHEDULE", "LOCATION_DETAILS", "TICKETS", "MEDIA", "LINKS"],
  "completionPercentage": 100,
  "canPublish": true,
  "createdAt": "2025-11-01T10:30:45+03:00",
  "updatedAt": "2025-12-01T14:20:30+03:00",
  "createdBy": "johndoe",
  "updatedBy": "johndoe"
}

Response Field Descriptions

Field	Type	Description
id	string (UUID)	Unique event identifier
title	string	Event title (3-200 chars)
slug	string	URL-friendly identifier (auto-generated with UUID suffix)
description	string	Event description (15-5000 chars when provided)
category	object	Category info (categoryId, categoryName, categorySlug)
eventFormat	enum	Event format: IN_PERSON, ONLINE, HYBRID
eventVisibility	enum	Visibility: PUBLIC, PRIVATE, UNLISTED
status	enum	Event status: DRAFT, PUBLISHED, HAPPENING, CANCELLED, COMPLETED
schedule	object	Schedule details including timezone and multi-day support
schedule.days	array	Array of day-specific schedules (for multi-day events)
venue	object	Physical location (required for IN_PERSON/HYBRID)
virtualDetails	object	Virtual meeting details (required for ONLINE/HYBRID)
media	object	Event media (banner, thumbnail, gallery)
linkedProducts	array	Attached products (max 10)
linkedShops	array	Attached shops (max 5)
tickets	array	Ticket types with availability info
organizer	object	Event organizer info
currentStage	enum	Current creation stage
completedStages	array	List of completed stages
completionPercentage	integer	Percentage of required stages completed (0-100)
canPublish	boolean	Whether event can be published (all required stages complete)
createdAt	string	ISO 8601 timestamp with timezone
updatedAt	string	ISO 8601 timestamp with timezone

Endpoints

1. Create Event Draft

Purpose: Initialize a new event draft (step 1 of event creation workflow)

Endpoint: POST {base_url}/e-events/draft

Access Level: 🔒 Protected (Requires Bearer Token Authentication)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token (format: `Bearer <token>`)
Content-Type	string	Yes	Must be `application/json`

Request JSON Sample:

{
  "title": "East African Tech Summit 2025",
  "categoryId": "660e8400-e29b-41d4-a716-446655440001",
  "eventFormat": "HYBRID"
}

Request Body Parameters:

Parameter	Type	Required	Description	Validation
title	string	Yes	Event title	Min: 3, Max: 200 characters
categoryId	string (UUID)	Yes	Category UUID	Must be active category
eventFormat	enum	Yes	Event format	Must be: IN_PERSON, ONLINE, or HYBRID

Success Response: Returns standard EventResponse structure with status DRAFT, currentStage BASIC_INFO, and BASIC_INFO marked as completed

Success Response Message: "Event draft created"

HTTP Status Code: 201 CREATED

Standard Error Types:

400 BAD_REQUEST: User already has a draft (one draft at a time rule)
401 UNAUTHORIZED: Authentication issues
404 NOT_FOUND: Category not found or user not authenticated
422 UNPROCESSABLE_ENTITY: Validation errors
500 INTERNAL_SERVER_ERROR: Server errors

Error Response Examples:

Already Has Draft (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "You already have an event draft. Complete or discard it first.",
  "action_time": "2025-12-11T10:30:45",
  "data": "You already have an event draft. Complete or discard it first."
}

Category Not Found (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Category not found",
  "action_time": "2025-12-11T10:30:45",
  "data": "Category not found"
}

2. Get Current Draft

Purpose: Retrieve the user's current active draft

Endpoint: GET {base_url}/e-events/draft

Access Level: 🔒 Protected

Authentication: Bearer Token

Success Response: Returns EventResponse if draft exists, or null data if no draft

Success Response Message: "Draft retrieved" (if draft exists) or "No draft found" (if no draft)

Success Response JSON Sample (No Draft):

{
  "success": true,
  "httpStatus": "OK",
  "message": "No draft found",
  "action_time": "2025-12-11T10:30:45",
  "data": null
}

3. Discard Draft

Purpose: Permanently delete the current draft

Endpoint: DELETE {base_url}/e-events/draft

Access Level: 🔒 Protected

Authentication: Bearer Token

Success Response Message: "Draft discarded"

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Draft discarded",
  "action_time": "2025-12-11T10:30:45",
  "data": null
}

Behavior:

Removes all associated data (linked products, shops, days)
Permanently deletes draft (not soft delete)
User can create new draft after discarding

Standard Error Types:

404 NOT_FOUND: No draft found to discard

4. Update Draft Basic Info

Purpose: Update basic event information (step 2 - refine details)

Endpoint: PATCH {base_url}/e-events/draft/basic-info

Access Level: 🔒 Protected

Authentication: Bearer Token

Request JSON Sample:

{
  "title": "East African Tech Summit 2025 - Updated",
  "description": "The premier annual technology conference bringing together innovators, developers, and entrepreneurs from across East Africa...",
  "categoryId": "660e8400-e29b-41d4-a716-446655440001",
  "eventVisibility": "PUBLIC",
  "eventFormat": "HYBRID"
}

Request Body Parameters (All Optional):

Parameter	Type	Required	Description	Validation
title	string	No	Updated title	Min: 3, Max: 200 characters
description	string	No	Event description	Min: 15, Max: 5000 characters
categoryId	string (UUID)	No	Updated category	Must be active category
eventVisibility	enum	No	Visibility level	PUBLIC, PRIVATE, or UNLISTED
eventFormat	enum	No	Event format	IN_PERSON, ONLINE, or HYBRID

Success Response: Returns updated EventResponse with currentStage set to SCHEDULE

Success Response Message: "Basic info updated"

Behavior:

Title change regenerates slug with new UUID suffix
Marks BASIC_INFO stage as completed
Advances currentStage to SCHEDULE
Format change may require updating location details (e.g., changing from IN_PERSON to HYBRID requires virtual details)

5. Update Draft Schedule

Purpose: Set event dates, times, and multi-day schedule (required stage)

Endpoint: PATCH {base_url}/e-events/draft/schedule

Access Level: 🔒 Protected

Authentication: Bearer Token

Request JSON Sample (Multi-Day Event):

{
  "timezone": "Africa/Nairobi",
  "days": [
    {
      "date": "2025-12-15",
      "startTime": "08:00:00",
      "endTime": "18:00:00",
      "description": "Opening day - Keynotes and workshops",
      "dayOrder": 1
    },
    {
      "date": "2025-12-16",
      "startTime": "09:00:00",
      "endTime": "17:00:00",
      "description": "Day 2 - Deep dive sessions",
      "dayOrder": 2
    },
    {
      "date": "2025-12-17",
      "startTime": "09:00:00",
      "endTime": "16:00:00",
      "description": "Final day - Hackathon presentations",
      "dayOrder": 3
    }
  ]
}

Request Body Parameters:

Parameter	Type	Required	Description	Validation
timezone	string	No	IANA timezone	Valid timezone (e.g., Africa/Nairobi), defaults to UTC
days	array	Yes	Event day schedules	Min: 1 day, must be chronological

Day Object Parameters:

Parameter	Type	Required	Description	Validation
date	string	Yes	Event date	Format: YYYY-MM-DD, cannot be in past
startTime	string	Yes	Start time	Format: HH:mm:ss (24-hour)
endTime	string	Yes	End time	Format: HH:mm:ss, must be after startTime
description	string	No	Day-specific description	Optional details for this day
dayOrder	integer	No	Day sequence number	Auto-assigned if not provided (1, 2, 3...)

Success Response: Returns updated EventResponse with schedule populated

Success Response Message: "Schedule updated"

Behavior:

Clears existing days before adding new ones
Sets event startDateTime from first day
Sets event endDateTime from last day
Validates chronological order
Validates no duplicate dates
Validates past dates not allowed
Marks SCHEDULE stage as completed
Advances currentStage to LOCATION_DETAILS

Standard Error Types:

400 BAD_REQUEST: Date in past, duplicate dates, end time before start time, days not in chronological order
404 NOT_FOUND: No draft found
422 UNPROCESSABLE_ENTITY: Validation errors

6. Update Draft Location

Purpose: Set venue (for in-person/hybrid) and/or virtual details (for online/hybrid)

Endpoint: PATCH {base_url}/e-events/draft/location

Access Level: 🔒 Protected

Authentication: Bearer Token

Request JSON Sample (Hybrid Event):

{
  "venue": {
    "name": "Nairobi Convention Centre",
    "address": "Harambee Avenue, Nairobi, Kenya",
    "coordinates": {
      "latitude": -1.2921,
      "longitude": 36.8219
    }
  },
  "virtualDetails": {
    "meetingLink": "https://zoom.us/j/1234567890",
    "meetingId": "123 456 7890",
    "passcode": "TechSummit2025"
  }
}

Request Body Parameters:

Parameter	Type	Required	Description	Validation
venue	object	Conditional	Physical venue details	Required for IN_PERSON/HYBRID
virtualDetails	object	Conditional	Virtual meeting details	Required for ONLINE/HYBRID

Venue Object Parameters:

Parameter	Type	Required	Description	Validation
name	string	Yes (if venue provided)	Venue name	Max: 200 characters
address	string	No	Physical address	Max: 500 characters
coordinates	object	No	GPS coordinates	Optional for mapping

Coordinates Object Parameters:

Parameter	Type	Required	Description	Validation
latitude	decimal	No	Latitude	Decimal degrees (-90 to 90)
longitude	decimal	No	Longitude	Decimal degrees (-180 to 180)

VirtualDetails Object Parameters:

Parameter	Type	Required	Description	Validation
meetingLink	string	Yes (if virtualDetails provided)	Meeting URL	Max: 500 characters
meetingId	string	No	Meeting ID	Max: 100 characters
passcode	string	No	Meeting passcode	Max: 100 characters

Success Response: Returns updated EventResponse with location details

Success Response Message: "Location updated"

Behavior:

Validation depends on eventFormat:
- IN_PERSON: Requires venue with name
- ONLINE: Requires virtualDetails with meetingLink
- HYBRID: Requires both venue and virtualDetails
Marks LOCATION_DETAILS stage as completed when requirements met
Advances currentStage to TICKETS when complete
Coordinates are optional but recommended for map display

7. Update Draft Media

Endpoint: PATCH {base_url}/e-events/draft/media

Access Level: 🔒 Protected

Authentication: Bearer Token

Request JSON Sample:

{
  "banner": "https://cdn.nexgate.com/events/summit-banner.jpg",
  "thumbnail": "https://cdn.nexgate.com/events/summit-thumb.jpg",
  "gallery": [
    "https://cdn.nexgate.com/events/gallery1.jpg",
    "https://cdn.nexgate.com/events/gallery2.jpg",
    "https://cdn.nexgate.com/events/gallery3.jpg"
  ]
}

Request Body Parameters:

Parameter	Type	Required	Description	Validation
banner	string	No	Banner image URL	Max: 500 characters
thumbnail	string	No	Thumbnail image URL	Max: 500 characters
gallery	array	No	Gallery image URLs	Max: 20 images

Success Response: Returns updated EventResponse with media populated

Success Response Message: "Media updated"

Behavior:

MEDIA stage is optional (not required for publishing)
Marks MEDIA stage as completed
Gallery limited to 20 images maximum
URLs should point to uploaded images (use separate file upload endpoint)

8. Attach Product to Draft

Purpose: Link a product to the event (for commerce integration)

Endpoint: POST {base_url}/e-events/draft/products/{productId}

Access Level: 🔒 Protected

Authentication: Bearer Token

Path Parameters:

Parameter	Type	Required	Description
productId	string (UUID)	Yes	UUID of product to attach

Success Response: Returns updated EventResponse with product in linkedProducts array

Success Response Message: "Product attached"

Behavior:

Product must be ACTIVE and not deleted
Maximum 10 products per event
Prevents duplicate attachments
Marks LINKS stage as completed
Product appears in event page for attendees to purchase

Standard Error Types:

400 BAD_REQUEST: Product already attached, max products reached
404 NOT_FOUND: Product not found or not active

9. Remove Product from Draft

Purpose: Unlink a product from the event

Endpoint: DELETE {base_url}/e-events/draft/products/{productId}

Access Level: 🔒 Protected

Authentication: Bearer Token

Path Parameters:

Parameter	Type	Required	Description
productId	string (UUID)	Yes	UUID of product to remove

Success Response: Returns updated EventResponse without the product

Success Response Message: "Product removed"

Standard Error Types:

404 NOT_FOUND: Product not attached to draft

10. Attach Shop to Draft

Purpose: Link a shop to the event (for commerce integration)

Endpoint: POST {base_url}/e-events/draft/shops/{shopId}

Access Level: 🔒 Protected

Authentication: Bearer Token

Path Parameters:

Parameter	Type	Required	Description
shopId	string (UUID)	Yes	UUID of shop to attach

Success Response: Returns updated EventResponse with shop in linkedShops array

Success Response Message: "Shop attached"

Behavior:

Shop must be ACTIVE and not deleted
Maximum 5 shops per event
Prevents duplicate attachments
Marks LINKS stage as completed

Standard Error Types:

400 BAD_REQUEST: Shop already attached, max shops reached
404 NOT_FOUND: Shop not found or not active

11. Remove Shop from Draft

Purpose: Unlink a shop from the event

Endpoint: DELETE {base_url}/e-events/draft/shops/{shopId}

Access Level: 🔒 Protected

Authentication: Bearer Token

Path Parameters:

Parameter	Type	Required	Description
shopId	string (UUID)	Yes	UUID of shop to remove

Success Response: Returns updated EventResponse without the shop

Success Response Message: "Shop removed"

Standard Error Types:

404 NOT_FOUND: Shop not attached to draft

12. Publish Event

Purpose: Publish the event (makes it publicly visible and generates RSA keys)

Endpoint: PATCH {base_url}/e-events/{eventId}/publish

Access Level: 🔒 Protected (Only event organizer)

Authentication: Bearer Token

Path Parameters:

Parameter	Type	Required	Description
eventId	string (UUID)	Yes	UUID of event to publish (typically from draft)

Success Response: Returns EventResponse with status PUBLISHED and RSA keys generated

Success Response Message: "Event published successfully"

Pre-Publish Validation Checks:

Required Stages Completed:
- ✅ BASIC_INFO (title, category, format)
- ✅ SCHEDULE (dates, times, timezone)
- ✅ LOCATION_DETAILS (venue for in-person/hybrid, virtual for online/hybrid)
- ✅ TICKETS (at least one active ticket type created)
Data Validation:
- Title present and valid
- Category present and active
- Start date not in past
- End date after start date
- Location complete based on format
- At least one ticket exists
Duplicate Detection:
- Similarity score < 85% for PUBLIC events
- Similarity score < 90% for PRIVATE events
- Similarity score < 95% for UNLISTED events
- Checks: Title (40%), Date (30%), Location (30%)
RSA Key Generation:
- Generates 2048-bit RSA key pair
- Stored securely for ticket signature verification
- Public key used in ticket QR codes

Behavior:

Changes status from DRAFT to PUBLISHED
Increments category event count
Sets publishedAt timestamp
Generates RSA keys if not present
Event becomes discoverable (if PUBLIC)
Tickets become available for purchase
Cannot be unpublished (only cancelled)

Standard Error Types:

400 BAD_REQUEST: Already published, duplicate event detected
403 FORBIDDEN: Not event organizer
404 NOT_FOUND: Event not found
422 UNPROCESSABLE_ENTITY: Required stages incomplete, validation errors

Error Response Examples:

Already Published (422):

{
  "success": false,
  "httpStatus": "UNPROCESSABLE_ENTITY",
  "message": "Event is already published",
  "action_time": "2025-12-11T10:30:45",
  "data": "Event is already published"
}

Missing Required Stage (422):

{
  "success": false,
  "httpStatus": "UNPROCESSABLE_ENTITY",
  "message": "SCHEDULE must be completed before publishing",
  "action_time": "2025-12-11T10:30:45",
  "data": "SCHEDULE must be completed before publishing"
}

Duplicate Event Detected (422):

{
  "success": false,
  "httpStatus": "UNPROCESSABLE_ENTITY",
  "message": "This event appears to be a duplicate of 'Tech Summit 2025' by jane_doe. Please make the title, date, or location more distinct.",
  "action_time": "2025-12-11T10:30:45",
  "data": "This event appears to be a duplicate of 'Tech Summit 2025' by jane_doe. Please make the title, date, or location more distinct."
}

Date in Past (422):

{
  "success": false,
  "httpStatus": "UNPROCESSABLE_ENTITY",
  "message": "Cannot publish event with start date in the past",
  "action_time": "2025-12-11T10:30:45",
  "data": "Cannot publish event with start date in the past"
}

13. Get Event by ID

Purpose: Retrieve a single event by its UUID

Endpoint: GET {base_url}/e-events/{eventId}

Access Level: 🔒 Protected

Authentication: Bearer Token

Path Parameters:

Parameter	Type	Required	Description
eventId	string (UUID)	Yes	UUID of event to retrieve

Success Response: Returns complete EventResponse structure

Success Response Message: "Event retrieved successfully"

Access Rules:

DRAFT events: Only organizer can view
PUBLISHED events: Anyone can view (if PUBLIC)
PRIVATE events: Only invited users can view (when invitation system is implemented)
UNLISTED events: Anyone with link can view

Standard Error Types:

403 FORBIDDEN: Trying to view another user's draft
404 NOT_FOUND: Event not found

14. Get My Events

Purpose: Retrieve all events created by authenticated user (paginated)

Endpoint: GET {base_url}/e-events/my-events

Access Level: 🔒 Protected

Authentication: Bearer Token

Query Parameters:

Parameter	Type	Required	Description	Default
page	integer	No	Page number (1-indexed)	1
size	integer	No	Items per page	10

Example URL: https://api.nexgate.com/api/v1/e-events/my-events?page=1&size=10

Success Response: Returns paginated EventResponse objects

Success Response Message: "Events retrieved successfully"

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Events retrieved successfully",
  "action_time": "2025-12-11T10:30:45",
  "data": {
    "content": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "title": "East African Tech Summit 2025",
        "status": "PUBLISHED",
        // ... full EventResponse
      }
    ],
    "pageable": {
      "pageNumber": 0,
      "pageSize": 10,
      "offset": 0
    },
    "totalPages": 3,
    "totalElements": 25,
    "last": false,
    "size": 10,
    "number": 0,
    "first": true,
    "empty": false
  }
}

Behavior:

Returns all statuses (DRAFT, PUBLISHED, HAPPENING, COMPLETED, CANCELLED)
Sorted by createdAt descending (newest first)
Only returns user's own events
Includes soft-deleted events excluded (isDeleted=false)

15. Get My Events by Status

Purpose: Retrieve user's events filtered by status (paginated)

Endpoint: GET {base_url}/e-events/my-events/status/{status}

Access Level: 🔒 Protected

Authentication: Bearer Token

Path Parameters:

Parameter	Type	Required	Description	Valid Values
status	enum	Yes	Event status filter	DRAFT, PUBLISHED, HAPPENING, CANCELLED, COMPLETED

Query Parameters:

Parameter	Type	Required	Description	Default
page	integer	No	Page number (1-indexed)	1
size	integer	No	Items per page	10

Example URL: https://api.nexgate.com/api/v1/e-events/my-events/status/PUBLISHED?page=1&size=10

Success Response: Returns paginated EventResponse objects matching status

Success Response Message: "Events retrieved successfully"

Use Cases:

DRAFT: View incomplete events needing completion
PUBLISHED: View upcoming published events
HAPPENING: View currently ongoing events
COMPLETED: View past events for analytics
CANCELLED: View cancelled events

Event Status Lifecycle

Status Flow Diagram

DRAFT → PUBLISHED → HAPPENING → COMPLETED
           ↓
       CANCELLED

Status Descriptions

Status	Description	Can Edit?	Can Delete?	Visible to Public?
DRAFT	Event is being created	Yes	Yes (hard delete)	No (organizer only)
PUBLISHED	Event is live and accepting registrations	Limited*	Soft delete only	Yes (based on visibility)
HAPPENING	Event is currently taking place	No**	No	Yes
COMPLETED	Event has ended	No	No	Yes (archived)
CANCELLED	Event was cancelled	No	No	Yes (marked cancelled)

* Limited editing on published events (media, description updates allowed; critical fields locked)
** Only administrative actions allowed during HAPPENING

Event Creation Stages

Stage Flow

BASIC_INFO (Required) → 2. SCHEDULE (Required) → 3. LOCATION_DETAILS (Required) → 4. TICKETS (Required) → 5. MEDIA (Optional) → 6. LINKS (Optional) → 7. REVIEW (Required)

Stage Details

Stage	Required	What to Complete	Progress Weight
BASIC_INFO	✅ Yes	Title, category, format, description, visibility	20%
SCHEDULE	✅ Yes	Dates, times, timezone, multi-day schedule	20%
LOCATION_DETAILS	✅ Yes	Venue (in-person), Virtual details (online), Both (hybrid)	20%
TICKETS	✅ Yes	At least one active ticket type	20%
MEDIA	❌ No	Banner, thumbnail, gallery	10%
LINKS	❌ No	Products, shops	10%
REVIEW	✅ Yes	Final validation before publish	10%

Completion Percentage Calculation:

Based on completed required stages only
Formula: (completed required stages / total required stages) × 100
Optional stages don't affect percentage
Example: If 3 of 5 required stages done = 60%

Duplicate Detection System

How It Works

The system prevents duplicate events using a sophisticated similarity algorithm:

Similarity Score Calculation (0-100%):

Title Similarity: 40% weight
- Levenshtein distance algorithm
- Normalized text comparison (lowercase, no special chars)
- Exact match = 100%, Substring match = 90%
Date Similarity: 30% weight
- Within 2 hours = 100%
- Within 6 hours = 90%
- Within 24 hours = 75%
- Within 48 hours = 60%
- Within 72 hours = 40%
Location Similarity: 30% weight
- Same venue name = 100%
- Within 100m = 95%
- Within 500m = 80%
- Within 2km = 50%
- Online events = 100% if both online

Thresholds by Visibility

Visibility	Block Threshold	Warning Threshold
PUBLIC	85%	75%
PRIVATE	90%	80%
UNLISTED	95%	85%

Duplicate Detection Rules

Blocked (similarity ≥ threshold):
- Cannot publish
- Error message shows similar event
- User must modify title, date, or location
Warning (similarity ≥ threshold - 10%):
- Can publish but shown warning
- Suggests reviewing similar event
- User can proceed if intentional
Allowed (similarity < warning threshold):
- No restrictions
- Event is sufficiently unique

Exemptions

Same organizer events (not checked)
UNLISTED events (excluded from search)
Events with same organizer but different dates
Events > 3 days apart

Commerce Integration

Linked Products

Purpose: Sell merchandise related to the event
Limit: Maximum 10 products per event
Requirements: Product must be ACTIVE and not deleted
Display: Products shown on event page
Use Cases: Event t-shirts, materials, recordings

Linked Shops

Purpose: Partner shops for event-related sales
Limit: Maximum 5 shops per event
Requirements: Shop must be ACTIVE and not deleted
Display: Shops shown on event page
Use Cases: Official vendors, sponsors, partners

Multi-Day Events

Day Structure

Events can span multiple days with individual schedules:

{
  "days": [
    {
      "date": "2025-12-15",
      "startTime": "08:00:00",
      "endTime": "18:00:00",
      "description": "Day 1 activities",
      "dayOrder": 1
    },
    {
      "date": "2025-12-16",
      "startTime": "09:00:00",
      "endTime": "17:00:00",
      "description": "Day 2 activities",
      "dayOrder": 2
    }
  ]
}

Multi-Day Rules

Minimum 1 day required
Days must be in chronological order
No duplicate dates allowed
Each day has independent start/end times
Event startDateTime = first day start
Event endDateTime = last day end
Each day can have description

RSA Key Security

Purpose

RSA keys secure ticket authenticity and prevent forgery:

Private Key: Held by platform, signs ticket QR codes
Public Key: Embedded in tickets, verifies signatures
Generation: 2048-bit keys generated on event publish
Storage: Stored securely in JSONB column
Usage: Each ticket QR contains signed data

Key Lifecycle

Generated once during first publish
Persists throughout event lifecycle
Used for all ticket validations
Never regenerated (maintains ticket validity)

Event Formats Explained

IN_PERSON

Physical venue required
Requires: venue.name, venue.address (recommended)
Optional: GPS coordinates for mapping
Attendees check in at physical location
Use cases: Conferences, concerts, workshops

ONLINE

Virtual meeting required
Requires: virtualDetails.meetingLink
Optional: meetingId, passcode
Attendees join via link
Use cases: Webinars, online courses, virtual meetups

HYBRID

Both venue AND virtual details required
Attendees choose in-person or online
Requires all location fields
Tickets can specify attendance mode
Use cases: Large conferences with remote option

Event Visibility Explained

PUBLIC

Discoverable in search/browse
Anyone can view event page
Appears in category listings
SEO indexed
Use cases: Public concerts, conferences, open events

PRIVATE

Not discoverable
Invite-only access (future feature)
Not in search results
Use cases: Corporate events, private parties

UNLISTED

Not discoverable
Anyone with link can view
Not in search results
Use cases: Beta events, soft launches

Quick Reference Guide

Common HTTP Status Codes

200 OK: Successful request
201 CREATED: Draft created successfully
400 Bad Request: Business rule violation (draft exists, duplicate event)
401 Unauthorized: Authentication required/failed
403 Forbidden: Not event organizer
404 Not Found: Event/draft not found
422 Unprocessable Entity: Validation errors, incomplete stages
500 Internal Server Error: Server error

One Draft Rule

Users can have only ONE draft at a time
Must publish or discard before creating new draft
Prevents accidental multiple drafts
Draft persists until explicitly discarded or published

Required vs Optional Stages

Required (Must Complete to Publish):

BASIC_INFO: Title, category, format
SCHEDULE: Dates, times, days
LOCATION_DETAILS: Venue/virtual based on format
TICKETS: At least one ticket type
REVIEW: Final validation

Optional (Enhances Event):

MEDIA: Images and gallery
LINKS: Products and shops

Data Format Standards

Dates: ISO 8601 with timezone (2025-12-15T18:00:00+03:00)
IDs: UUID format
Slugs: Generated with UUID suffix for uniqueness
Times: 24-hour format (HH:mm:ss)
Coordinates: Decimal degrees (latitude, longitude)

Best Practices

Event Creation:
- Start with clear, descriptive title
- Choose appropriate category
- Set realistic dates/times
- Provide complete location details
- Add compelling media
- Create multiple ticket tiers
Duplicate Prevention:
- Use specific titles (not "Tech Event")
- Include year/edition in title
- Verify dates don't conflict
- Check existing events before creating
Multi-Day Events:
- Order days chronologically
- Provide day-specific descriptions
- Set realistic daily schedules
- Account for breaks between days
Commerce Integration:
- Link relevant products only
- Choose active shops
- Test product links work
- Update inventory before publish

Error Handling Tips

422 Errors: Check completedStages array to see what's missing
400 Draft Exists: Discard or complete existing draft first
Duplicate Detection: Modify title/date/location to differentiate
403 Forbidden: Ensure you're the event organizer

Nexgate-Event-mng-Requrements

Nexgate Platform - Check-in System Architecture

NEXGATE EVENT MANAGEMENT PLATFORM

Event Management System - Requirements & User Flow Documentation

Events Management API

Ticket Management API

Event Checkout & Payment API

Event Booking Orders API

Event Check-In System API

Organizer Analytics API

Attendance Analytics API

Event Feedback API

Events Management API

Standard Response Format

Success Response Structure

Error Response Structure

HTTP Method Badge Standards

EventResponse Structure

Response Field Descriptions

Endpoints

1. Create Event Draft

2. Get Current Draft

3. Discard Draft

4. Update Draft Basic Info

5. Update Draft Schedule

6. Update Draft Location

7. Update Draft Media

8. Attach Product to Draft

9. Remove Product from Draft

10. Attach Shop to Draft

11. Remove Shop from Draft

12. Publish Event

13. Get Event by ID

14. Get My Events

15. Get My Events by Status

Event Status Lifecycle

Status Flow Diagram

Status Descriptions

Event Creation Stages

Stage Flow

Stage Details

Duplicate Detection System

How It Works

Thresholds by Visibility

Duplicate Detection Rules

Exemptions

Commerce Integration

Linked Products

Linked Shops

Multi-Day Events

Day Structure

Multi-Day Rules

RSA Key Security

Purpose

Key Lifecycle

Event Formats Explained

IN_PERSON

ONLINE

HYBRID

Event Visibility Explained

PUBLIC

PRIVATE

UNLISTED

Quick Reference Guide

Common HTTP Status Codes

One Draft Rule

Required vs Optional Stages

Data Format Standards

Best Practices

Error Handling Tips