Events API

Overview

The Events API allows you to create and manage events within workspaces. Events are the core entity in EventPalour and support various types, pricing models, and ticketing options.

Create Event

Create a new event in a workspace.

import { createEvent } from '@/app/actions/events';
import { EventType, EventPricing } from '@/lib/db/schema/enums';

const result = await createEvent({
  title: 'Tech Conference 2024',
  description: '<p>Join us for an amazing tech conference...</p>',
  workspaceId: 'workspace_id',
  type: EventType.PHYSICAL,
  pricing: EventPricing.PAID,
  venue: 'Convention Center',
  country: 'Kenya',
  city: 'Nairobi',
  startDate: new Date('2024-06-01T09:00:00'),
  endDate: new Date('2024-06-03T18:00:00'),
  category: 'Technology',
  eventImageUrl: 'https://storage.example.com/event-image.jpg',
});

Parameters

title

string

required

Event title (1-255 characters)

description

string

required

Event description in HTML format (10-5000 characters of plain text)

workspaceId

string

required

ID of the workspace creating the event

type

EventType

required

Event type: physical, online, or hybrid

pricing

EventPricing

required

Pricing model: free or paid

startDate

Date

required

Event start date and time

endDate

Date

required

Event end date and time (must be after startDate)

venue

string

Physical venue name (required for physical and hybrid events)

country

string

Country where event takes place

city

string

City where event takes place

Response

success

boolean

Whether the event was created successfully

eventId

string

ID of the created event

shortId

string

6-character short ID for the event (e.g., abc123)

error

string

Error message if creation failed

Example Response

{
  "success": true,
  "eventId": "evt_a1b2c3d4e5f6",
  "shortId": "abc123"
}

Event Types

EventPalour supports three event types:

Physical
Online
Hybrid

In-person events at a physical location.Required fields:

venue
country
city

{
  type: EventType.PHYSICAL,
  venue: 'Conference Center',
  country: 'Kenya',
  city: 'Nairobi'
}

Virtual events conducted online.Required fields:

meetingPlatform
meetingLink

{
  type: EventType.ONLINE,
  meetingPlatform: 'zoom',
  meetingLink: 'https://zoom.us/j/123456789'
}

Events with both physical and online components.Required fields:

venue, country, city
meetingPlatform, meetingLink

{
  type: EventType.HYBRID,
  venue: 'Convention Center',
  country: 'Kenya',
  city: 'Nairobi',
  meetingPlatform: 'zoom',
  meetingLink: 'https://zoom.us/j/123456789'
}

Pricing Models

Free Events

Free events allow open registration without payment:

{
  pricing: EventPricing.FREE,
  // No KYC required
  // No ticket pricing needed
}

Paid Events

Paid events require ticket purchases:

{
  pricing: EventPricing.PAID,
  // KYC verification required for organizer
  ticketTypes: JSON.stringify([
    {
      name: 'Early Bird',
      price: 50.00,
      currency: 'USD',
      availability: 100
    }
  ])
}

KYC Required: Organizers must complete KYC verification before creating paid events. The API will return an error if KYC is not approved.

Validation Rules

The Events API validates:

Title Validation

Required: Cannot be empty
Length: 1-255 characters

title: z.string()
  .min(1, "Title is required")
  .max(255, "Title must be 255 characters or less")

Description Validation

Required: Cannot be empty
Length: 10-5000 characters (plain text, excluding HTML tags)
Format: HTML content

description: z.string()
  .refine(val => getPlainTextLength(val) >= 10)
  .refine(val => getPlainTextLength(val) <= 5000)

Date Validation

Start Date: Required
End Date: Required, must be after start date
Format: ISO 8601 date string or Date object

.refine(
  (data) => data.endDate > data.startDate,
  {
    message: "End date must be after start date",
    path: ["endDate"],
  }
)

Type-Specific Validation

Physical Events:

Venue required
Location (country, city) recommended

Online Events:

Meeting platform required
Meeting link required and must be valid URL

Hybrid Events:

All physical AND online requirements

Event Categories

Categories help organize events. You can:

Use existing category:
```
{ categoryId: 'existing_category_id' }
```

Auto-create by name:

{ category: 'Technology' }  // Creates if doesn't exist

Create custom category:

{ customCategory: 'AI & Machine Learning' }

Event Status Management

Events have four statuses:

enum EventStatus {
  ACTIVE = "active",        // Event is live and accepting registrations
  INACTIVE = "inactive",    // Event is hidden/draft
  CANCELED = "canceled",    // Event has been canceled
  POSTPONED = "postponed"   // Event date postponed
}

Default status is ACTIVE. Change status using updateEvent().

Permissions Required

Minimum Role: ModeratorTo create events, users must have at least Moderator role in the workspace.

// Permission check (automatic in createEvent)
const { workspace, role } = await validateWorkspaceAccess(
  workspaceId,
  WorkspaceRole.MODERATOR
);

Get Event Details

Retrieve event information:

import { getEventById } from '@/dal/events';

const event = await getEventById('event_id');

string

Unique event identifier

short_id

string

6-character short ID

title

string

Event title

description

string

Event description (HTML)

status

EventStatus

Current event status

type

EventType

Event type (physical/online/hybrid)

pricing

EventPricing

Pricing model (free/paid)

workspace_id

string

ID of workspace that owns the event

start_date

Date

Event start date and time

end_date

Date

Event end date and time

venue

string | null

Physical venue name

meeting_link

string | null

Online meeting URL

created_at

Date

Event creation timestamp

updated_at

Date

Last update timestamp

Error Handling

Common event creation errors:

Error	Cause	Solution
`"Authentication required"`	No session	Sign in first
`"Workspace not found"`	Invalid workspace ID	Verify workspace exists
`"Only moderators and above can create events"`	Insufficient permissions	Upgrade role to Moderator
`"KYC verification required for paid events"`	Organizer KYC not approved	Complete KYC process
`"End date must be after start date"`	Invalid date range	Fix date values
`"Description must be at least 10 characters"`	Description too short	Add more detail

Complete Example

Creating a hybrid event with tickets:

import { createEvent } from '@/app/actions/events';
import { EventType, EventPricing } from '@/lib/db/schema/enums';

const ticketTypes = [
  {
    name: 'Early Bird',
    price: 50.00,
    currency: 'USD',
    availability: 100,
    valid_from: new Date('2024-01-01'),
    valid_until: new Date('2024-03-01')
  },
  {
    name: 'Regular',
    price: 75.00,
    currency: 'USD',
    availability: 200,
    valid_from: new Date('2024-03-01'),
    valid_until: new Date('2024-06-01')
  },
  {
    name: 'VIP',
    price: 150.00,
    currency: 'USD',
    availability: 50
  }
];

const result = await createEvent({
  // Basic Info
  title: 'East Africa Tech Summit 2024',
  description: '<p>The largest technology conference in East Africa...</p>',
  workspaceId: 'wks_abc123',
  
  // Event Type & Pricing
  type: EventType.HYBRID,
  pricing: EventPricing.PAID,
  
  // Physical Location
  venue: 'Kenyatta International Convention Centre',
  country: 'Kenya',
  city: 'Nairobi',
  
  // Online Meeting
  meetingPlatform: 'zoom',
  meetingLink: 'https://zoom.us/j/987654321',
  
  // Dates
  startDate: new Date('2024-06-15T09:00:00'),
  endDate: new Date('2024-06-17T18:00:00'),
  
  // Category
  category: 'Technology',
  
  // Image
  eventImageUrl: 'https://storage.eventpalour.com/events/summit-2024.jpg',
  
  // Tickets
  ticketTypes: JSON.stringify(ticketTypes),
  
  // Partners/Sponsors
  partners: JSON.stringify([
    {
      name: 'TechCorp',
      logo: 'https://example.com/logo.png',
      website: 'https://techcorp.com'
    }
  ])
});

if (result.success) {
  console.log('Event created:', result.eventId);
  console.log('Short URL:', `https://eventpalour.com/events/${result.shortId}`);
} else {
  console.error('Failed to create event:', result.error);
}

Next Steps

Tickets API

Add and manage event tickets

Payments API

Handle ticket payments

Workspaces API

Manage workspace settings

Event Management

Learn about event features

Overview

Endpoints

Overview

Create Event

Parameters

Response

Example Response

Event Types

Pricing Models

Free Events

Paid Events

Validation Rules

Event Categories

Event Status Management

Permissions Required

Get Event Details

Error Handling

Complete Example

Next Steps

Tickets API

Payments API

Workspaces API

Event Management

Build docs developers (and LLMs) love

Overview

Endpoints

​Overview

​Create Event

​Parameters

​Response

​Example Response

​Event Types

​Pricing Models

​Free Events

​Paid Events

​Validation Rules

​Event Categories

​Event Status Management

​Permissions Required

​Get Event Details

​Error Handling

​Complete Example

​Next Steps

Tickets API

Payments API

Workspaces API

Event Management

Build docs developers (and LLMs) love

Overview

Create Event

Parameters

Response

Example Response

Event Types

Pricing Models

Free Events

Paid Events

Validation Rules

Event Categories

Event Status Management

Permissions Required

Get Event Details

Error Handling

Complete Example

Next Steps