Path Parameters :
Parameter
Type
Required
Description
Validation
eventId
UUID
Yes
Event identifier
Must be owned by the authenticated organizer
ticketInstanceId
UUID
Yes
Individual ticket instance identifier
Must belong to a booking under this event
Success Response JSON Sample :
{
"success": true,
"httpStatus": "OK",
"message": "Attendee detail retrieved",
"action_time": "2026-05-23T10:30:45",
"data": {
"ticketInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa8",
"formResponseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"attendeeNumber": "EVT-A3F4B21C-VIP-0042",
"attendeeName": "John Doe",
"attendeeEmail": "john@example.com",
"attendeePhone": "+255712345678",
"ticketType": "VIP Pass",
"ticketSeries": "VIP-0042",
"bookingReference": "EVT-A3F4B21C",
"pricePaid": 150.00,
"overallStatus": "PARTIALLY_ATTENDED",
"daysAttended": 2,
"daysTotal": 3,
"checkInsByDay": [
{
"dayNumber": 1,
"dayName": "Day 1 - Opening",
"dayDate": "2026-12-15",
"status": "CHECKED_IN",
"checkInTime": "2026-12-15T09:15:00+03:00",
"checkInLocation": "Main Gate",
"checkedInBy": "Scanner Operator 1",
"scannerId": "3fa85f64-5717-4562-b3fc-2c963f66afb0"
},
{
"dayNumber": 2,
"dayName": "Day 2 - Conference",
"dayDate": "2026-12-16",
"status": "NOT_CHECKED_IN",
"checkInTime": null,
"checkInLocation": null,
"checkedInBy": null,
"scannerId": null
},
{
"dayNumber": 3,
"dayName": "Day 3 - Closing",
"dayDate": "2026-12-17",
"status": "UPCOMING",
"checkInTime": null,
"checkInLocation": null,
"checkedInBy": null,
"scannerId": null
}
]
}
}
Success Response Fields :
Field
Description
data.ticketInstanceId
Unique ticket instance UUID
data.formResponseId
UUID of the buyer's applicant form response — null if the event had no form
data.attendeeNumber
Unique readable ID = bookingReference + "-" + ticketSeries
data.overallStatus
PRESENT (all days), PARTIALLY_ATTENDED (some), ABSENT (none)
data.daysAttended
Count of days this ticket was checked in
data.daysTotal
Total number of event days
data.checkInsByDay[].status
CHECKED_IN , NOT_CHECKED_IN , or UPCOMING
data.checkInsByDay[].checkInTime
null when not checked in or day is upcoming
data.checkInsByDay[].checkedInBy
Name of the scanner operator who processed the check-in
Error Response JSON Sample :
{
"success": false,
"httpStatus": "NOT_FOUND",
"message": "Ticket not found",
"action_time": "2026-05-23T10:30:45",
"data": "Ticket not found"
}
Standard Error Types :
401 UNAUTHORIZED : Missing or invalid token
403 FORBIDDEN : Authenticated user is not the event organizer
404 NOT_FOUND : Event not found or ticket instance does not belong to this event
Quick Reference Guide
Attendance Status Values
Value
Meaning
Available when
PRESENT
Checked in (all days if no day filter)
Always
ABSENT
Never checked in
Always
PARTIALLY_ATTENDED
Checked in some days but not all
No dayNumber filter, multi-day events only
Day Status Values
Value
Meaning
CHECKED_IN
Ticket was scanned on that day
NOT_CHECKED_IN
Day passed, ticket not scanned
UPCOMING
Day has not started yet
Buyer Type Values
Value
buyerEmail
buyerId
Meaning
SYSTEM_USER
Populated
Populated
Bought online, has platform account
AT_DOOR
null
null
Walk-in sale, name only captured at door
Common HTTP Status Codes
200 OK : Successful request
401 UNAUTHORIZED : Authentication required or token invalid
403 FORBIDDEN : Not the event organizer
404 NOT_FOUND : Event, ticket, or day number not found
500 INTERNAL_SERVER_ERROR : Unexpected server error
Event Feedback 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 Event Feedback API enables attendees to rate and review events after attendance. This API provides a simple 5-star rating system with optional comments, prevents duplicate feedback, ensures only attendees (non-organizers) can submit reviews, and allows anyone to view event feedback with pagination. The system supports escrow release decisions based on feedback quality and helps organizers improve future events.
Hints :
One Feedback Per User : Each user can only submit one feedback per event
Attendee Only : Event organizers cannot review their own events
5-Star Rating : Required rating from 1-5 stars
Optional Comments : Text reviews up to 1000 characters
Public Viewing : Anyone can view event feedback (paginated)
Chronological Order : Newest feedback first
Escrow Integration : Feedback may influence escrow release (future)
Simple Model : Focus on rating quality over complex metrics
Response Structure
EventFeedbackResponse
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"eventId": "770e8400-e29b-41d4-a716-446655440002",
"eventTitle": "East African Tech Summit 2025",
"userId": "660e8400-e29b-41d4-a716-446655440001",
"userName": "johndoe",
"rating": 5,
"comment": "Amazing event! The speakers were excellent and the venue was perfect. Definitely attending next year!",
"createdAt": "2025-12-18T10:30:45Z"
}
Paginated Response
{
"success": true,
"httpStatus": "OK",
"message": "Feedbacks retrieved successfully",
"action_time": "2025-12-11T10:30:45",
"data": {
"content": [
{
"id": "uuid",
"eventId": "uuid",
"eventTitle": "East African Tech Summit 2025",
"userId": "uuid",
"userName": "johndoe",
"rating": 5,
"comment": "Great event!",
"createdAt": "2025-12-18T10:30:45Z"
}
],
"pageable": {
"pageNumber": 0,
"pageSize": 20,
"offset": 0
},
"totalElements": 145,
"totalPages": 8,
"last": false,
"first": true,
"numberOfElements": 20,
"size": 20,
"number": 0,
"empty": false
}
}
Endpoints
1. Create Feedback
Endpoint : POST /feedbacks/event/{eventId}
Access : 🔒 Authenticated Users (Non-Organizers)
Path Parameters :
Parameter
Type
Required
Description
eventId
string (UUID)
Yes
Event identifier
Request Headers :
Header
Type
Required
Description
Authorization
string
Yes
Bearer token
Content-Type
string
Yes
application/json
Request Body :
{
"rating": 5,
"comment": "Amazing event! The speakers were excellent and the venue was perfect. Definitely attending next year!"
}
Request Parameters :
Parameter
Type
Required
Description
Validation
rating
integer
Yes
Star rating
Min: 1, Max: 5
comment
string
No
Text review
Max: 1000 characters
Success Response : Returns EventFeedbackResponse
Success Response Message : "Feedback submitted successfully"
HTTP Status Code : 201 CREATED
Behavior :
Validates user is authenticated
Validates event exists
Checks user is NOT the event organizer
Checks user hasn't already submitted feedback
Creates feedback record
Returns created feedback
Validation Rules :
✅ Rating must be 1-5 (integer)
✅ Comment optional, max 1000 chars
✅ One feedback per user per event
✅ Organizers cannot review own events
✅ Event must exist
Standard Error Types :
400 BAD_REQUEST : Invalid rating (not 1-5)
401 UNAUTHORIZED : Not authenticated
403 FORBIDDEN : Organizer trying to review own event
404 NOT_FOUND : Event not found
409 CONFLICT : Already submitted feedback
Error Response Examples :
Invalid Rating (400):
{
"success": false,
"httpStatus": "BAD_REQUEST",
"message": "Rating must be at least 1",
"action_time": "2025-12-11T10:30:45",
"data": "Rating must be at least 1"
}
Organizer Cannot Review (403):
{
"success": false,
"httpStatus": "FORBIDDEN",
"message": "Event organizers cannot submit feedback for their own events.",
"action_time": "2025-12-11T10:30:45",
"data": "Event organizers cannot submit feedback for their own events."
}
Already Submitted (409):
{
"success": false,
"httpStatus": "CONFLICT",
"message": "You have already provided feedback for this event",
"action_time": "2025-12-11T10:30:45",
"data": "You have already provided feedback for this event"
}
2. Get Event Feedbacks
Endpoint : GET /feedbacks/event/{eventId}?page=0&size=20
Access : 🔓 Public (No Authentication Required)
Path Parameters :
Parameter
Type
Required
Description
eventId
string (UUID)
Yes
Event identifier
Query Parameters :
Parameter
Type
Required
Description
page
integer
No
Page number (0-indexed, default: 0)
size
integer
No
Items per page (default: 20)
Success Response : Returns Spring Page object with EventFeedbackResponse items
Success Response Message : "Feedbacks retrieved successfully"
HTTP Status Code : 200 OK
Behavior :
Returns paginated list of feedback
Sorted by creation date (newest first)
No authentication required (public access)
Validates event exists
Pagination Details :
Zero-indexed pages (0, 1, 2...)
Default page size: 20
Max page size: 100 (recommended)
Includes total elements and pages
Standard Error Types :
404 NOT_FOUND : Event not found
Rating System
Star Ratings (1-5)
Rating
Meaning
Emoji
Description
5 ⭐⭐⭐⭐⭐
Excellent
😍
Outstanding event, exceeded expectations
4 ⭐⭐⭐⭐
Very Good
😊
Great event, minor improvements possible
3 ⭐⭐⭐
Good
🙂
Satisfactory event, met expectations
2 ⭐⭐
Fair
😐
Below expectations, needs improvement
1 ⭐
Poor
😞
Disappointing event, significant issues
Average Rating Calculation
Average = Sum of all ratings / Number of feedbacks
Example :
Ratings: 5, 5, 4, 5, 3, 4, 5, 5, 4, 5
Total: 45
Count: 10
Average: 4.5 stars
Display Format : 4.5 ⭐ (10 reviews)
Comment Guidelines
Recommended Comment Content
Good Comments Include :
✅ What you enjoyed
✅ Specific highlights (speakers, venue, activities)
✅ Suggestions for improvement
✅ Overall experience summary
Example Good Comments :
"Amazing event! The keynote speakers were excellent and provided valuable insights.
The venue was perfect and well-organized. Only suggestion would be to have longer
lunch breaks. Will definitely attend next year!"
"Great networking opportunities and diverse range of topics. Sound system could
be improved in the main hall."
"Well organized but sessions felt rushed. Would prefer fewer sessions with more
time for Q&A."
Avoid :
❌ Offensive language
❌ Personal attacks
❌ Spam or promotional content
❌ Off-topic comments
Character Limit
Maximum: 1000 characters
Recommended: 100-500 characters
Minimum: None (optional field)
Access Control
Who Can Submit Feedback?
Allowed :
✅ Any authenticated user
✅ Attendees (purchased tickets)
✅ Non-attendees (also allowed currently)
Not Allowed :
❌ Event organizers (for their own events)
❌ Users who already submitted feedback
❌ Unauthenticated users
Future Restriction (Recommended):
Only users who purchased tickets
Requires checking booking history
Prevents fake reviews
Who Can View Feedback?
Anyone (Public access):
✅ No authentication required
✅ Potential attendees researching events
✅ Event organizers viewing their reviews
✅ Platform admins
Use Cases
Submit Feedback After Event
POST /feedbacks/event/{eventId}
{
"rating": 5,
"comment": "Great event, highly recommend!"
}
User provides honest review after attending
View Event Reviews Before Booking
GET /feedbacks/event/{eventId}?page=0&size=20
Potential attendee checks reviews before purchasing tickets
Sees average rating and recent comments
Organizer Checks Feedback
GET /feedbacks/event/{eventId}?page=0&size=20
Organizer views all feedback for their event
Identifies areas for improvement
Plans better future events
Platform Quality Monitoring
GET /feedbacks/event/{eventId}?page=0&size=20
Platform admin reviews feedback
Identifies low-rated events
May influence escrow release decisions
Future Enhancements
Planned Features
1. Verified Attendee Badge
Only show "Verified Attendee" if user has booking
Increases trust in reviews
Current: Anyone can review (not implemented)
2. Average Rating Endpoint
GET /feedbacks/event/{eventId}/summary
{
"averageRating": 4.5,
"totalReviews": 145,
"ratingDistribution": {
"5": 90,
"4": 35,
"3": 15,
"2": 3,
"1": 2
}
}
3. Helpful Votes
Users can mark reviews as helpful
Sort by most helpful
Bubble up quality reviews
4. Organizer Response
Organizers can reply to feedback
Shows engagement and care
Builds trust with future attendees
5. Escrow Integration
Average rating influences escrow release
Events <3 stars may require manual review
Automatic release for 4+ stars
Current: Not implemented
Escrow Release Logic (Future)
How Feedback May Affect Escrow
High Ratings (4-5 stars average):
✅ Automatic escrow release
Indicates successful event
No manual review needed
Medium Ratings (3-3.9 stars average):
⚠️ Manual review triggered
Platform checks for issues
May contact organizer
Usually released after review
Low Ratings (<3 stars average):
❌ Escrow release delayed
Investigation required
May require organizer explanation
Possible refunds if serious issues
Example :
Event with 4.5 average rating (90% 5-star):
→ Escrow automatically released 24 hours after event
Event with 2.8 average rating (50% 1-2 star):
→ Escrow held, manual review, contact organizer
→ Possible partial refunds if issues confirmed
Current Status : Not implemented (all events release automatically)
Best Practices
For Attendees
✅ Submit honest, constructive feedback
✅ Mention specific positives and negatives
✅ Wait until after event to review
✅ Be respectful in comments
✅ Update review if organizer addresses issues (future)
For Organizers
✅ Read all feedback carefully
✅ Identify patterns in complaints
✅ Thank reviewers for positive feedback (future)
✅ Address concerns in organizer response (future)
✅ Use feedback to improve future events
For Platform
✅ Monitor feedback quality
✅ Flag suspicious reviews
✅ Use ratings in escrow decisions (future)
✅ Display average ratings prominently
✅ Encourage verified attendee reviews (future)
Quick Reference
HTTP Status Codes
200 OK : Feedbacks retrieved successfully
201 CREATED : Feedback submitted successfully
400 BAD_REQUEST : Invalid rating value
401 UNAUTHORIZED : Not authenticated
403 FORBIDDEN : Organizer reviewing own event
404 NOT_FOUND : Event not found
409 CONFLICT : Already submitted feedback
Rating Range
Minimum : 1 star (Poor)
Maximum : 5 stars (Excellent)
Type : Integer only (no half stars)
Comment Length
Minimum : 0 (optional)
Maximum : 1000 characters
Recommended : 100-500 characters
Pagination
Default Page : 0 (first page)
Default Size : 20 items
Max Size : 100 (recommended)
Sort Order : Newest first (createdAt DESC)
Data Formats
Event ID : UUID format
User ID : UUID format
Created At : ISO 8601 timestamp (Instant)
Rating : Integer (1-5)
Integration Examples
Submit Feedback Form
const submitFeedback = async (eventId, rating, comment) => {
const response = await fetch(`/api/v1/e-events/feedbacks/event/${eventId}`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({ rating, comment })
});
if (response.status === 201) {
alert('Thank you for your feedback!');
} else if (response.status === 409) {
alert('You have already reviewed this event');
} else if (response.status === 403) {
alert('Organizers cannot review their own events');
}
};
Display Feedback List
const loadFeedback = async (eventId, page = 0) => {
const response = await fetch(
`/api/v1/e-events/feedbacks/event/${eventId}?page=${page}&size=20`
);
const data = await response.json();
const feedbacks = data.data.content;
const averageRating = calculateAverage(feedbacks);
displayFeedbacks(feedbacks, averageRating);
};
const calculateAverage = (feedbacks) => {
if (feedbacks.length === 0) return 0;
const sum = feedbacks.reduce((acc, f) => acc + f.rating, 0);
return (sum / feedbacks.length).toFixed(1);
};
Star Rating Component
const StarRating = ({ rating, onChange }) => {
const stars = [1, 2, 3, 4, 5];
return (
{stars.map(star => (
onChange(star)}
>
⭐
))}
);
};
Conclusion
The Event Feedback API provides simple yet effective review system with:
✅ 5-Star Ratings : Simple and universally understood
✅ Optional Comments : Detailed written feedback
✅ One Per User : Prevents spam and duplicate reviews
✅ Organizer Protection : Can't review own events
✅ Public Access : Anyone can view to inform decisions
✅ Pagination : Handles large numbers of reviews
✅ Future Integration : Ready for escrow release logic
Event Fund Claims
Author : Josh S. Sakweli, Backend Lead — QBIT SPARK CO LIMITED
Version : v1.0
Base URL : /api/v1/e-events/claims
Overview
When an event organizer sells tickets, revenue is held in escrow — one escrow entry per buyer checkout session. A Fund Claim is a formal request to release all currently HELD escrows for an event into the organizer's wallet. Every claim goes through a PENDING → APPROVED / REJECTED lifecycle, and funds only move on explicit admin approval.
Claim approval is an all-or-nothing escrow operation — it releases every HELD escrow for that event at the moment of approval. Partial escrow release is not supported by design (see Financial Safety ). What the organizer does with the wallet balance after release is handled by the separate DisbursementService .
Authentication : All endpoints require Authorization: Bearer
Business Rules
Rule
Detail
One pending per event
At most ONE PENDING claim per event at any time
Claimable amount formula
totalRevenue − totalRefunded − totalClaimed − totalPendingClaims
Admin-only for active events
If event has not ended, only ADMIN can initiate a claim
Refund deadline
3 days before event start. Past this → no refunds, organizer may claim early
Escrow release
Approval releases ALL HELD escrows for the event atomically → organizer wallet. No partial release
No partial amounts
Escrows are atomic per buyer. "80% release" has no business meaning at the escrow layer — staging happens via DisbursementService after funds land in wallet
Admin claims require note
adminNote is mandatory on admin-initiated claims
Refund safety
Refunds and approvals use pessimistic write lock on EscrowAccount to prevent race conditions
Claim Status Lifecycle
Status
Meaning
PENDING
Submitted, awaiting admin review. Escrow NOT yet released
APPROVED
Admin approved. Escrow atomically released to organizer wallet
REJECTED
Admin rejected. No funds moved. Organizer may submit a new claim
CANCELLED
Organizer cancelled before admin action. No funds moved
Standard Response Format
Success
{
"success": true,
"httpStatus": "OK",
"message": "Fund claim submitted successfully",
"action_time": "2026-04-27T10:30:45",
"data": { }
}
Error
{
"success": false,
"httpStatus": "BAD_REQUEST",
"message": "A pending claim already exists for this event",
"action_time": "2026-04-27T10:30:45",
"data": "A pending claim already exists for this event"
}
Endpoints
1. List All Claims (Admin)
Endpoint : GET /api/v1/e-events/claims
Access : 🔒 ROLE_SUPER_ADMIN or ROLE_STAFF_ADMIN
Purpose : Returns all fund claims across all events. Optionally filter by status.
Query Parameters :
Parameter
Type
Required
Description
Default
status
ClaimStatus enum
No
Filter by: PENDING , APPROVED , REJECTED , CANCELLED
— (all returned)
Success Response :
{
"success": true,
"httpStatus": "OK",
"message": "Fund claims retrieved",
"data": [
{
"claimId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"claimNumber": "EFC-2026-000001",
"eventId": "uuid",
"eventTitle": "Dar Jazz Night",
"eventStatus": "PUBLISHED",
"organizerId": "uuid",
"organizerName": "Amina Hassan",
"status": "PENDING",
"claimedAmount": 50000.00,
"totalRevenueSnapshot": 80000.00,
"totalRefundedSnapshot": 5000.00,
"totalPreviouslyClaimedSnapshot": 0.00,
"totalPendingAtSubmission": 0.00,
"currency": "TZS",
"adminInitiated": false,
"adminId": null,
"adminNote": null,
"organizerNote": "Requesting first partial claim",
"reviewedById": null,
"reviewerName": null,
"reviewNote": null,
"reviewedAt": null,
"escrowsReleasedCount": 0,
"escrowsSkippedCount": 0,
"actualReleasedAmount": null,
"initiatedAt": "2026-04-20T08:00:00",
"updatedAt": "2026-04-20T08:00:00"
}
]
}
Response Fields :
Field
Type
Description
claimId
UUID
Unique claim identifier
claimNumber
string
Human-readable reference, e.g. EFC-2026-000001
eventId
UUID
The event this claim belongs to
eventTitle
string
Display name of the event
eventStatus
EventStatus
Current event status
organizerId
UUID
Organizer's account ID
organizerName
string
Organizer's display name
status
ClaimStatus
Current claim status
claimedAmount
BigDecimal
Amount the organizer requested
totalRevenueSnapshot
BigDecimal
Organizer's net revenue at time of submission
totalRefundedSnapshot
BigDecimal
Total refunds issued at time of submission
totalPreviouslyClaimedSnapshot
BigDecimal
Already released to wallet before this claim
totalPendingAtSubmission
BigDecimal
Other pending claim amounts at submission time
currency
string
Currency code, e.g. TZS
adminInitiated
boolean
true if an admin submitted on behalf of organizer
adminId
UUID
Admin's account ID (null if organizer-initiated)
adminNote
string
Admin's reason for initiating (null if organizer-initiated)
organizerNote
string
Optional note from organizer
reviewedById
UUID
ID of admin who reviewed (null if pending)
reviewerName
string
Name of reviewing admin (null if pending)
reviewNote
string
Admin's review note (null if pending)
reviewedAt
LocalDateTime
Timestamp of review (null if pending)
escrowsReleasedCount
Integer
Number of escrow entries released on approval
escrowsSkippedCount
Integer
Escrow entries skipped (e.g. already refunded)
actualReleasedAmount
BigDecimal
Actual amount credited to wallet on approval
initiatedAt
LocalDateTime
When the claim was submitted
updatedAt
LocalDateTime
Last updated timestamp
Possible Errors :
HTTP Status
Description
401 UNAUTHORIZED
Invalid or expired JWT
403 FORBIDDEN
Caller does not have admin role
2. Get My Claims (Organizer)
Endpoint : GET /api/v1/e-events/claims/my-claims
Access : 🔒 Authenticated organizer (any role)
Purpose : Returns all fund claims submitted by the currently authenticated organizer, across all their events.
No query parameters.
Success Response :
{
"success": true,
"httpStatus": "OK",
"message": "My fund claims retrieved",
"data": [ /* array of EventFundClaimResponse — same structure as endpoint 1 */ ]
}
Possible Errors :
HTTP Status
Description
401 UNAUTHORIZED
Invalid or expired JWT
3. Get Claim by ID
Endpoint : GET /api/v1/e-events/claims/{claimId}
Access : 🔒 Authenticated — admin sees any claim; organizer sees only their own
Purpose : Returns full details of a single fund claim.
Path Parameters :
Parameter
Type
Required
Description
claimId
UUID
Yes
The claim's unique identifier
Success Response :
{
"success": true,
"httpStatus": "OK",
"message": "Claim retrieved",
"data": { /* EventFundClaimResponse */ }
}
Possible Errors :
HTTP Status
Description
401 UNAUTHORIZED
Invalid or expired JWT
403 FORBIDDEN
Organizer attempting to view another organizer's claim
404 NOT_FOUND
Claim with given ID does not exist
4. Get Event Claims
Endpoint : GET /api/v1/e-events/claims/event/{eventId}
Access : 🔒 Authenticated — organizer (own events) or admin (any event)
Purpose : Returns all claims ever submitted for a specific event.
Path Parameters :
Parameter
Type
Required
Description
eventId
UUID
Yes
The event's unique identifier
Success Response :
{
"success": true,
"httpStatus": "OK",
"message": "Event claims retrieved",
"data": [ /* array of EventFundClaimResponse */ ]
}
Possible Errors :
HTTP Status
Description
401 UNAUTHORIZED
Invalid or expired JWT
403 FORBIDDEN
Organizer does not own this event
404 NOT_FOUND
Event not found
5. Get Claimable Amount
Endpoint : GET /api/v1/e-events/claims/event/{eventId}/claimable-amount
Access : 🔒 Authenticated — organizer (own events) or admin
Purpose : Returns the current claimable amount breakdown for an event, including eligibility status and the active pending claim if one exists.
Path Parameters :
Parameter
Type
Required
Description
eventId
UUID
Yes
The event's unique identifier
Success Response :
{
"success": true,
"httpStatus": "OK",
"message": "Claimable amount retrieved",
"data": {
"eventId": "uuid",
"eventTitle": "Dar Jazz Night",
"totalRevenue": 80000.00,
"totalRefunded": 5000.00,
"totalClaimed": 0.00,
"totalPendingClaims": 0.00,
"claimableAmount": 60000.00,
"currency": "TZS",
"eligible": true,
"ineligibilityReason": null,
"activePendingClaimId": null,
"refundDeadline": "2026-05-10T00:00:00+03:00",
"pastRefundDeadline": false
}
}
Note on claimable amount : claimableAmount = totalRevenue − totalRefunded − totalClaimed − totalPendingClaims . This is a snapshot estimate used to indicate eligibility — the actualReleasedAmount on approval is the real number, as it reflects the live HELD escrow balance at the moment of approval.
Response Fields :
Field
Type
Description
totalRevenue
BigDecimal
Net organizer share of all non-refunded tickets
totalRefunded
BigDecimal
Gross amount returned to buyers
totalClaimed
BigDecimal
Already released to organizer wallet
totalPendingClaims
BigDecimal
Locked by current PENDING claims
claimableAmount
BigDecimal
What the organizer can claim right now
eligible
boolean
Whether a new claim can be submitted
ineligibilityReason
string
Human-readable reason if eligible = false
activePendingClaimId
UUID
ID of the existing pending claim, or null
refundDeadline
ZonedDateTime
eventStartDate − 3 days
pastRefundDeadline
boolean
true = refund window closed, full amount claimable
Possible Errors :
HTTP Status
Description
401 UNAUTHORIZED
Invalid or expired JWT
403 FORBIDDEN
Organizer does not own this event
404 NOT_FOUND
Event not found
6. Get Revenue Summary (Admin)
Endpoint : GET /api/v1/e-events/claims/event/{eventId}/revenue-summary
Access : 🔒 ROLE_SUPER_ADMIN or ROLE_STAFF_ADMIN
Purpose : Returns a full financial summary of an event including gross sales, platform fees, refunds, claimed amounts, and escrow balance. Used for admin audit and oversight.
Path Parameters :
Parameter
Type
Required
Description
eventId
UUID
Yes
The event's unique identifier
Success Response :
{
"success": true,
"httpStatus": "OK",
"message": "Event revenue summary retrieved",
"data": {
"eventId": "uuid",
"eventTitle": "Dar Jazz Night",
"grossRevenue": 100000.00,
"totalRefunded": 5000.00,
"platformFees": 10000.00,
"netOrganizerRevenue": 85000.00,
"totalClaimed": 0.00,
"totalPendingClaims": 0.00,
"escrowBalance": 85000.00,
"currency": "TZS"
}
}
Possible Errors :
HTTP Status
Description
401 UNAUTHORIZED
Invalid or expired JWT
403 FORBIDDEN
Caller does not have admin role
404 NOT_FOUND
Event not found
7. Submit Claim (Organizer)
Endpoint : POST /api/v1/e-events/claims/event/{eventId}
Access : 🔒 Authenticated organizer — must own the event
Purpose : Organizer submits a fund claim for the full current claimable amount. The claim amount is computed server-side — organizer cannot override it.
Path Parameters :
Parameter
Type
Required
Description
eventId
UUID
Yes
The event to submit a claim for
Request Body (optional):
{
"organizerNote": "Requesting first partial claim before event ends"
}
Request Body Fields :
Field
Type
Required
Description
Validation
organizerNote
string
No
Optional note from the organizer
Max 1000 characters
Guard Rules Applied Server-Side :
Event must belong to the authenticated organizer
Event must have ended OR pastRefundDeadline = true (otherwise only admin can claim)
claimableAmount must be > 0
No existing PENDING claim for this event
Success Response :
{
"success": true,
"httpStatus": "OK",
"message": "Fund claim submitted successfully",
"data": { /* EventFundClaimResponse with status: PENDING */ }
}
Possible Errors :
HTTP Status
Description
400 BAD_REQUEST
A pending claim already exists for this event
400 BAD_REQUEST
Claimable amount is zero — nothing to claim
400 BAD_REQUEST
Event has not ended and refund deadline has not passed — only admin can claim
401 UNAUTHORIZED
Invalid or expired JWT
403 FORBIDDEN
Authenticated user does not own this event
404 NOT_FOUND
Event not found
8. Admin-Initiate Claim
Endpoint : POST /api/v1/e-events/claims/event/{eventId}/admin-initiate
Access : 🔒 ROLE_SUPER_ADMIN or ROLE_STAFF_ADMIN
Purpose : Admin submits a fund claim on behalf of the organizer. Used when the event is still active (ticket sales ongoing). The claim is flagged adminInitiated = true with a mandatory audit note.
Path Parameters :
Parameter
Type
Required
Description
eventId
UUID
Yes
The event to claim funds for
Request Body :
{
"adminNote": "Organizer requested early release. Event ending tomorrow, no pending refunds."
}
Request Body Fields :
Field
Type
Required
Description
Validation
adminNote
string
Yes
Mandatory reason for admin-initiated claim
Not blank
Guard Rules Applied Server-Side :
claimableAmount must be > 0
No existing PENDING claim for this event
Claim is capped at claimableAmount (never full totalRevenue )
Success Response :
{
"success": true,
"httpStatus": "OK",
"message": "Admin-initiated claim created",
"data": {
"claimId": "uuid",
"claimNumber": "EFC-2026-000003",
"status": "PENDING",
"adminInitiated": true,
"adminId": "uuid-of-admin",
"adminNote": "Organizer requested early release. Event ending tomorrow, no pending refunds.",
"claimedAmount": 64000.00,
"currency": "TZS"
}
}
Possible Errors :
HTTP Status
Description
400 BAD_REQUEST
A pending claim already exists for this event
400 BAD_REQUEST
Claimable amount is zero — nothing to claim
401 UNAUTHORIZED
Invalid or expired JWT
403 FORBIDDEN
Caller does not have admin role
404 NOT_FOUND
Event not found
422 UNPROCESSABLE_ENTITY
adminNote is blank
9. Approve Claim (Admin)
Endpoint : POST /api/v1/e-events/claims/{claimId}/approve
Access : 🔒 ROLE_SUPER_ADMIN or ROLE_STAFF_ADMIN
Purpose : Admin approves a pending claim. This atomically acquires a pessimistic write lock on the EscrowAccount , fetches all escrows currently in HELD status for the event, releases every one of them, and credits the full released amount to the organizer's wallet.
Design note : Approval releases ALL HELD escrows — not just the claimedAmount subset. Each escrow is atomic (one buyer's payment for one checkout session) so partial release has no valid business meaning. The claimedAmount on the claim is a snapshot estimate taken at submission time. The actualReleasedAmount stored on approval is the authoritative number — it reflects the live HELD balance at the moment the admin approves, and may differ if refunds were processed in between.
Path Parameters :
Parameter
Type
Required
Description
claimId
UUID
Yes
The claim to approve
Request Body (optional):
{
"reviewNote": "Verified escrow balance. Approved for release."
}
Request Body Fields :
Field
Type
Required
Description
reviewNote
string
No
Optional note from reviewing admin
Critical : Approval acquires a PESSIMISTIC_WRITE lock on the EscrowAccount row. Concurrent refund operations for the same event will block until the approval transaction completes, preventing escrow from going negative.
Success Response :
{
"success": true,
"httpStatus": "OK",
"message": "Fund claim approved and funds released",
"data": {
"claimId": "uuid",
"claimNumber": "EFC-2026-000001",
"status": "APPROVED",
"claimedAmount": 50000.00,
"actualReleasedAmount": 48000.00,
"escrowsReleasedCount": 12,
"escrowsSkippedCount": 1,
"reviewedById": "admin-uuid",
"reviewerName": "Admin John",
"reviewNote": "Verified escrow balance. Approved for release.",
"reviewedAt": "2026-04-27T14:30:00"
}
}
Note on actualReleasedAmount : May be less than claimedAmount if one or more escrow entries were refunded between claim submission and admin approval. The escrowsSkippedCount indicates how many entries were skipped for this reason.
Possible Errors :
HTTP Status
Description
400 BAD_REQUEST
Claim is not in PENDING status
400 BAD_REQUEST
Escrow balance insufficient to cover claim amount
401 UNAUTHORIZED
Invalid or expired JWT
403 FORBIDDEN
Caller does not have admin role
404 NOT_FOUND
Claim not found
10. Reject Claim (Admin)
Endpoint : POST /api/v1/e-events/claims/{claimId}/reject
Access : 🔒 ROLE_SUPER_ADMIN or ROLE_STAFF_ADMIN
Purpose : Admin rejects a pending claim. No funds are moved. The organizer may submit a new claim after rejection.
Path Parameters :
Parameter
Type
Required
Description
claimId
UUID
Yes
The claim to reject
Request Body (optional):
{
"reviewNote": "Pending dispute investigation. Please resubmit after resolution."
}
Request Body Fields :
Field
Type
Required
Description
reviewNote
string
No
Reason for rejection (shown to organizer)
Success Response :
{
"success": true,
"httpStatus": "OK",
"message": "Fund claim rejected",
"data": {
"claimId": "uuid",
"claimNumber": "EFC-2026-000001",
"status": "REJECTED",
"reviewedById": "admin-uuid",
"reviewerName": "Admin John",
"reviewNote": "Pending dispute investigation. Please resubmit after resolution.",
"reviewedAt": "2026-04-27T14:35:00"
}
}
Possible Errors :
HTTP Status
Description
400 BAD_REQUEST
Claim is not in PENDING status
401 UNAUTHORIZED
Invalid or expired JWT
403 FORBIDDEN
Caller does not have admin role
404 NOT_FOUND
Claim not found
11. Cancel Claim (Organizer)
Endpoint : DELETE /api/v1/e-events/claims/{claimId}
Access : 🔒 Authenticated organizer — must be the claim owner
Purpose : Organizer cancels their own pending claim before any admin action. This frees up the pending amount, allowing a new claim to be submitted.
Path Parameters :
Parameter
Type
Required
Description
claimId
UUID
Yes
The claim to cancel
No request body.
Success Response :
{
"success": true,
"httpStatus": "OK",
"message": "Fund claim cancelled",
"data": null
}
Possible Errors :
HTTP Status
Description
400 BAD_REQUEST
Claim is not in PENDING status (already reviewed)
401 UNAUTHORIZED
Invalid or expired JWT
403 FORBIDDEN
Organizer does not own this claim
404 NOT_FOUND
Claim not found
Financial Safety: Refund & Claim Concurrency
This section explains how the system prevents money from being over-released when a refund and a claim approval happen simultaneously, and why partial escrow release is not supported.
Why Partial Release Is Not Supported
Each escrow is atomic — it represents one buyer's payment for one checkout session. To release "80% of claimable funds" the service would have to arbitrarily pick specific escrow entries to release and leave others HELD . There is no business logic that justifies which individual buyer's payment stays locked — the organizer delivered the event to all of them equally.
10 escrows × 950 TZS = 9,500 TZS claimable
"Release 80%" = 7,600 TZS = release 8 escrows, hold 2
→ WHY are those 2 buyers' payments still locked?
→ No valid answer exists at the escrow layer.
The correct model is:
Claim approval → ALL HELD escrows released → Organizer wallet (full amount lands)
↓
Organizer controls staged
payouts via DisbursementService
The organizer's wallet is the right layer for staged payouts. The claim domain's job is simply: verify eligibility, get admin approval, atomically convert all HELD escrows into wallet balance.
The Race Condition Risk
Revenue = 10,000 TZS in HELD escrows
PENDING claim submitted
→ Refund of 2,000 processed concurrently
→ Claim approved → releases all HELD (now 8,000)
→ Refund deducts 2,000 from already-decremented escrow
→ Escrow goes negative 💀
Protections in Place
Layer
Mechanism
Refund deadline
No refunds allowed within 3 days of event. Eliminates the race entirely post-deadline.
Pessimistic DB lock
Both approveClaim() and processRefund() acquire PESSIMISTIC_WRITE lock on the EscrowAccount row — serializing the two operations.
Balance check
Before any deduction, service verifies escrow.balance >= amount . Throws InsufficientEscrowException if not.
Snapshot vs actual
claimedAmount is a snapshot estimate at submission time. actualReleasedAmount is the real released amount at approval time — reflects live HELD balance after any intervening refunds.
escrowsSkippedCount
Tracks how many escrow entries were already REFUNDED or DISPUTED at approval time and therefore skipped.
Claimable Amount Formula
claimableAmount = totalRevenue − totalRefunded − totalClaimed − totalPendingClaims
This formula gives an estimate of what's claimable. The actual amount released on approval equals the live sum of all HELD escrow sellerAmount values at that moment.
Endpoint Quick Reference
#
Method
Path
Access
Description
1
GET
/claims
Admin
List all claims (filter by status)
2
GET
/claims/my-claims
Organizer
Get my own claims
3
GET
/claims/{claimId}
Organizer / Admin
Get single claim by ID
4
GET
/claims/event/{eventId}
Organizer / Admin
Get all claims for an event
5
GET
/claims/event/{eventId}/claimable-amount
Organizer / Admin
Get claimable amount breakdown
6
GET
/claims/event/{eventId}/revenue-summary
Admin
Full event revenue summary
7
POST
/claims/event/{eventId}
Organizer
Submit a new claim
8
POST
/claims/event/{eventId}/admin-initiate
Admin
Admin-initiate claim for active event
9
POST
/claims/{claimId}/approve
Admin
Approve claim + release escrow
10
POST
/claims/{claimId}/reject
Admin
Reject claim
11
DELETE
/claims/{claimId}
Organizer
Cancel pending claim
Standard Error Reference
HTTP Status
Scenario
400 BAD_REQUEST
Business rule violation (duplicate pending, zero claimable, wrong status)
401 UNAUTHORIZED
Missing, expired, or malformed JWT
403 FORBIDDEN
Insufficient role or ownership violation
404 NOT_FOUND
Event or claim does not exist
422 UNPROCESSABLE_ENTITY
Validation failure (e.g. blank adminNote )
500 INTERNAL_SERVER_ERROR
Unexpected server error
Exproling
Attendee Questions API Guide
What Is It?
A customizable questionnaire system that event organizers attach to their events to collect information from attendees during registration. Think of it like Google Forms, but built specifically for events and integrated into the ticket purchase flow.
The Two Sides
Organizer Side (Building the Form)
When an organizer creates an event, they can optionally enable "Attendee Questions." The system automatically creates an empty form with one page. The organizer then builds their questionnaire by:
Adding pages - to organize questions into logical sections (e.g., "Personal Info", "Dietary Needs", "Travel Details")
Adding fields to pages - choosing from various field types like text, email, phone, dropdowns, checkboxes, ratings, file uploads, etc.
Adding options - for choice-based fields (dropdown, radio, checkbox), the organizer adds the available choices
Configuring settings - deciding when to show the form (before or after checkout), whether it's required, and if walk-in attendees should also complete it
The organizer can reorder pages, fields, and options. They can edit labels, add descriptions, set validation rules (minimum length, date ranges, file size limits), and mark fields as required or optional.
Attendee Side (Filling the Form)
When someone registers for a published event, they see the questionnaire. The system works page-by-page:
View a page - attendee sees one page of questions at a time with navigation showing progress (Page 1 of 3)
Fill and save - as the attendee completes a page and moves to the next, their answers are validated and saved automatically. If any answer is invalid (wrong format, too short, invalid selection), the page won't save and they see specific error messages for each problematic field.
Submit - when ready, the attendee clicks submit. The system checks ALL pages to ensure every required field is answered and all answers are valid. If everything passes, the submission is finalized. If not, they see a summary showing which pages have problems.
The key principle: validate before saving, never store invalid data . This keeps the database clean and gives immediate feedback.
The Analytics Side (Viewing Results)
Once attendees start submitting, the organizer can view comprehensive analytics:
Summary statistics - total submissions, completion rates, average time to complete, submission trends over time, and which pages have the highest drop-off rates
Field-by-field breakdown - for each question, see response rates and detailed analysis. For choice fields, see how many people selected each option with percentages. For numeric fields, see averages, ranges, and distributions. For text fields, see common words and length statistics.
Spreadsheet view - all responses in a table format, like Google Forms' response spreadsheet, with each row being one submission and each column being one question
Export - download all data as CSV or Excel for external analysis
How Is It Useful?
For Event Organizers
Logistics planning:
Collect t-shirt sizes to order the right quantities
Gather dietary requirements for catering
Know arrival times for transportation planning
Get emergency contact information for safety
Attendee profiling:
Ask about interests for personalized experiences
Collect company/role info for networking features
Understand how attendees heard about the event for marketing
Compliance and safety:
Collect required documents (ID uploads)
Gather health declarations
Get consent for photography/recording
Verify age requirements
Engagement:
Ask what sessions attendees plan to attend
Collect questions for Q&A panels
Gather song requests for performers
Get feedback on previous events
For Attendees
Smoother experience:
Complete registration in one flow instead of separate forms
Save progress and return later (draft mode)
Clear validation messages prevent submission errors
Know exactly what's required vs optional
Personalization:
Their preferences are captured for a tailored experience
Dietary needs are communicated without awkward conversations
Special requirements are noted in advance
Real-World Example
Music Festival Scenario:
An organizer creates a 3-day festival. They enable attendee questions with two pages:
Page 1: Essential Info
Emergency contact name (required, text)
Emergency contact phone (required, phone validation)
T-shirt size (required, dropdown: S/M/L/XL)
Camping or day pass? (required, radio)
Page 2: Preferences
Dietary restrictions (optional, checkbox: vegetarian, vegan, gluten-free, halal, kosher)
Other dietary notes (optional, textarea)
Which headliner are you most excited for? (optional, dropdown with artist names)
When 500 people register, the organizer sees:
65% chose Medium or Large t-shirts
23% have dietary restrictions (42% of those are vegetarian)
Artist X is the most anticipated headliner with 45% of votes
Page 2 has 15% drop-off (people skipping optional questions)
They export the data to:
Order t-shirts: 50 S, 180 M, 170 L, 100 XL
Tell catering: 115 vegetarian meals, 45 vegan, 60 gluten-free
Adjust sound check priority based on headliner popularity
Why This Design?
Page-by-page saves prevent data loss. If someone fills 3 pages then loses internet, they don't lose everything.
Strict validation before saving means the database only contains valid, usable data. No garbage entries to clean up later.
Empty-body submit means the final submission is just a validation check, not a data transfer. Everything is already saved from auto-saves.
Parallel page validation on submit makes the final check fast even with many pages.
Separation of draft and published means organizers can freely edit their form while building the event, but once published and people start responding, the structure is stable.
Summary
It's a form builder tailored for events. Organizers build custom questionnaires, attendees fill them page-by-page with auto-save and validation, and organizers get rich analytics to plan better events. The technical design prioritizes data integrity, user experience, and actionable insights.
System Flow
┌─────────────────────────────────────────────────────────────────────────────┐
│ ORGANIZER FLOW │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ 1. Create Event Draft │
│ POST /api/v1/e-events/drafts │
│ ↓ │
│ 2. Enable Attendee Questions │
│ PUT /api/v1/e-events/drafts/{draftId}/attendee-questions │
│ ↓ │
│ 3. Add Pages (optional - default page created automatically) │
│ POST /api/v1/e-events/drafts/{draftId}/attendee-questions/pages │
│ ↓ │
│ 4. Add Fields to Pages │
│ POST /api/v1/e-events/drafts/{draftId}/attendee-questions/pages/{pageId}/fields │
│ ↓ │
│ 5. Add Options to Choice Fields (dropdown/radio/checkbox) │
│ POST /api/v1/e-events/drafts/{draftId}/attendee-questions/fields/{fieldId}/options │
│ ↓ │
│ 6. Publish Event │
│ POST /api/v1/e-events/drafts/{draftId}/publish │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐
│ ATTENDEE FLOW │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ 1. View Questionnaire (check if registration open) │
│ GET /api/v1/e-events/{eventId}/attendee-questions │
│ ↓ │
│ 2. Get Each Page │
│ GET /api/v1/e-events/{eventId}/attendee-questions/pages/{pageNumber} │
│ ↓ │
│ 3. Save Page Answers (auto-save per page) │
│ PATCH /api/v1/e-events/{eventId}/attendee-questions/responses/pages/{n}│
│ ↓ │
│ 4. Submit Final Response │
│ POST /api/v1/e-events/{eventId}/attendee-questions/responses/submit │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐
│ ANALYTICS FLOW (Organizer Only) │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ GET /api/v1/e-events/{eventId}/attendee-questions/analytics/summary │
│ GET /api/v1/e-events/{eventId}/attendee-questions/analytics/fields │
│ GET /api/v1/e-events/{eventId}/attendee-questions/analytics/fields/{id} │
│ GET /api/v1/e-events/{eventId}/attendee-questions/analytics/responses │
│ GET /api/v1/e-events/{eventId}/attendee-questions/analytics/export/csv │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Authentication
All endpoints require JWT authentication except public event viewing.
Header: Authorization: Bearer {jwt_token}
PART 1: ORGANIZER ENDPOINTS
Base URL
/api/v1/e-events/drafts/{draftId}/attendee-questions
1.1 Enable Attendee Questions
Creates a new questionnaire for the event draft. Automatically creates an empty form with one default page.
Endpoint:
PUT /api/v1/e-events/drafts/{draftId}/attendee-questions
Request:
{
"displayTime": "BEFORE_CHECKOUT",
"isRequiredOnline": true,
"applyToAtDoor": false
}
Request Fields:
Field
Type
Required
Description
displayTime
enum
No
When to show form: BEFORE_CHECKOUT or AFTER_CHECKOUT . Default: BEFORE_CHECKOUT
isRequiredOnline
boolean
No
Must complete before checkout? Default: false
applyToAtDoor
boolean
No
Show to walk-in attendees? Default: false
Response (201 Created):
{
"success": true,
"httpStatus": "CREATED",
"message": "Attendee questions enabled",
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"eventId": "660e8400-e29b-41d4-a716-446655440001",
"formId": "770e8400-e29b-41d4-a716-446655440002",
"displayTime": "BEFORE_CHECKOUT",
"isRequiredOnline": true,
"applyToAtDoor": false,
"createdAt": "2025-01-23T10:30:00Z",
"updatedAt": "2025-01-23T10:30:00Z"
}
}
Error Responses:
Status
Message
404
Draft not found
403
You don't have access to this draft
403
Attendee questions already enabled. Use update instead.
1.2 Update Attendee Questions Settings
Endpoint:
PATCH /api/v1/e-events/drafts/{draftId}/attendee-questions
Request:
{
"displayTime": "AFTER_CHECKOUT",
"isRequiredOnline": false
}
All fields optional - only updates provided fields.
Response (200 OK):
{
"success": true,
"httpStatus": "OK",
"message": "Settings updated",
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"eventId": "660e8400-e29b-41d4-a716-446655440001",
"formId": "770e8400-e29b-41d4-a716-446655440002",
"displayTime": "AFTER_CHECKOUT",
"isRequiredOnline": false,
"applyToAtDoor": false,
"createdAt": "2025-01-23T10:30:00Z",
"updatedAt": "2025-01-23T10:35:00Z"
}
}
1.3 Get Attendee Questions (with full form)
Endpoint:
GET /api/v1/e-events/drafts/{draftId}/attendee-questions
Response (200 OK):
{
"success": true,
"httpStatus": "OK",
"message": "Attendee questions retrieved",
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"eventId": "660e8400-e29b-41d4-a716-446655440001",
"formId": "770e8400-e29b-41d4-a716-446655440002",
"displayTime": "BEFORE_CHECKOUT",
"isRequiredOnline": true,
"applyToAtDoor": false,
"createdAt": "2025-01-23T10:30:00Z",
"updatedAt": "2025-01-23T10:30:00Z",
"form": {
"formId": "770e8400-e29b-41d4-a716-446655440002",
"title": "Attendee Questions - Music Festival 2025",
"description": "Custom questions for event attendees",
"pages": [
{
"pageId": "880e8400-e29b-41d4-a716-446655440003",
"title": "Personal Information",
"description": "Basic attendee details",
"displayOrder": 1,
"fields": [
{
"fieldId": "990e8400-e29b-41d4-a716-446655440004",
"type": "TEXT",
"label": "Emergency Contact Name",
"description": "Who should we contact in case of emergency?",
"placeholder": "Full name",
"displayOrder": 1,
"required": true,
"validation": {
"minLength": 2,
"maxLength": 100
},
"options": []
},
{
"fieldId": "aa0e8400-e29b-41d4-a716-446655440005",
"type": "PHONE",
"label": "Emergency Contact Phone",
"displayOrder": 2,
"required": true,
"options": []
},
{
"fieldId": "bb0e8400-e29b-41d4-a716-446655440006",
"type": "DROPDOWN",
"label": "T-Shirt Size",
"displayOrder": 3,
"required": true,
"options": [
{"optionId": "opt1", "label": "Small", "displayOrder": 1},
{"optionId": "opt2", "label": "Medium", "displayOrder": 2},
{"optionId": "opt3", "label": "Large", "displayOrder": 3},
{"optionId": "opt4", "label": "X-Large", "displayOrder": 4}
]
}
]
},
{
"pageId": "cc0e8400-e29b-41d4-a716-446655440007",
"title": "Dietary Requirements",
"displayOrder": 2,
"fields": [
{
"fieldId": "dd0e8400-e29b-41d4-a716-446655440008",
"type": "CHECKBOX",
"label": "Dietary Restrictions",
"description": "Select all that apply",
"displayOrder": 1,
"required": false,
"options": [
{"optionId": "opt5", "label": "Vegetarian", "displayOrder": 1},
{"optionId": "opt6", "label": "Vegan", "displayOrder": 2},
{"optionId": "opt7", "label": "Gluten-free", "displayOrder": 3},
{"optionId": "opt8", "label": "Halal", "displayOrder": 4},
{"optionId": "opt9", "label": "Kosher", "displayOrder": 5}
]
},
{
"fieldId": "ee0e8400-e29b-41d4-a716-446655440009",
"type": "TEXTAREA",
"label": "Other Dietary Notes",
"placeholder": "Any allergies or special requirements?",
"displayOrder": 2,
"required": false
}
]
}
]
}
}
}
Response when not configured (200 OK):
{
"success": true,
"httpStatus": "OK",
"message": "Attendee questions not configured",
"data": null
}
1.4 Disable Attendee Questions
Permanently deletes the form and all configuration.
Endpoint:
DELETE /api/v1/e-events/drafts/{draftId}/attendee-questions
Response (200 OK):
{
"success": true,
"httpStatus": "OK",
"message": "Attendee questions disabled"
}
Pages Management
1.5 Add Page
Endpoint:
POST /api/v1/e-events/drafts/{draftId}/attendee-questions/pages
Request:
{
"title": "Travel Information",
"description": "Help us plan your arrival"
}
Response (201 Created):
{
"success": true,
"httpStatus": "CREATED",
"message": "Page added",
"data": {
"pageId": "ff0e8400-e29b-41d4-a716-446655440010",
"title": "Travel Information",
"description": "Help us plan your arrival",
"displayOrder": 3
}
}
1.6 Update Page
Endpoint:
PATCH /api/v1/e-events/drafts/{draftId}/attendee-questions/pages/{pageId}
Request:
{
"title": "Travel & Accommodation",
"description": "Updated description"
}
Response (200 OK):
{
"success": true,
"httpStatus": "OK",
"message": "Page updated",
"data": {
"pageId": "ff0e8400-e29b-41d4-a716-446655440010",
"title": "Travel & Accommodation",
"description": "Updated description",
"displayOrder": 3
}
}
1.7 Delete Page
Endpoint:
DELETE /api/v1/e-events/drafts/{draftId}/attendee-questions/pages/{pageId}
Response (200 OK):
{
"success": true,
"httpStatus": "OK",
"message": "Page deleted"
}
1.8 Reorder Pages
Endpoint:
POST /api/v1/e-events/drafts/{draftId}/attendee-questions/pages/reorder
Request:
{
"orderedIds": [
"cc0e8400-e29b-41d4-a716-446655440007",
"880e8400-e29b-41d4-a716-446655440003",
"ff0e8400-e29b-41d4-a716-446655440010"
]
}
Response (200 OK):
{
"success": true,
"httpStatus": "OK",
"message": "Pages reordered"
}
Fields Management
1.9 Add Field
Endpoint:
POST /api/v1/e-events/drafts/{draftId}/attendee-questions/pages/{pageId}/fields
Request (Text Field):
{
"type": "TEXT",
"label": "Company Name",
"description": "Your current employer",
"placeholder": "Enter company name",
"required": false,
"validation": {
"minLength": 2,
"maxLength": 100
}
}
Request (Dropdown Field):
{
"type": "DROPDOWN",
"label": "How did you hear about us?",
"required": true
}
Request (Rating Field):
{
"type": "RATING",
"label": "How excited are you for this event?",
"required": true,
"validation": {
"min": 1,
"max": 5
}
}
Request (File Upload Field):
{
"type": "FILE",
"label": "Upload ID Document",
"description": "Government-issued ID for verification",
"required": true,
"validation": {
"maxSizeMb": 5,
"accept": "image/*,.pdf"
}
}
Available Field Types:
Type
Description
Has Options
TEXT
Single line text
No
TEXTAREA
Multi-line text
No
EMAIL
Email with validation
No
PHONE
Phone number
No
NUMBER
Numeric input
No
DATE
Date picker
No
TIME
Time picker
No
DATETIME
Date and time
No
DROPDOWN
Single select dropdown
Yes
RADIO
Single select radio buttons
Yes
CHECKBOX
Multi-select checkboxes
Yes
RATING
Star rating
No
SCALE
Linear scale (1-10)
No
SLIDER
Slider input
No
FILE
File upload
No
URL
URL with validation
No
CURRENCY
Money input
No
SECTION_HEADER
Display only - section title
No
PARAGRAPH
Display only - text block
No
Response (201 Created):
{
"success": true,
"httpStatus": "CREATED",
"message": "Field added",
"data": {
"fieldId": "110e8400-e29b-41d4-a716-446655440011",
"type": "DROPDOWN",
"label": "How did you hear about us?",
"displayOrder": 1,
"required": true,
"options": []
}
}
1.10 Update Field
Endpoint:
PATCH /api/v1/e-events/drafts/{draftId}/attendee-questions/fields/{fieldId}
Request:
{
"label": "How did you discover this event?",
"required": false,
"description": "Help us improve our marketing"
}
Response (200 OK):
{
"success": true,
"httpStatus": "OK",
"message": "Field updated",
"data": {
"fieldId": "110e8400-e29b-41d4-a716-446655440011",
"type": "DROPDOWN",
"label": "How did you discover this event?",
"description": "Help us improve our marketing",
"displayOrder": 1,
"required": false,
"options": []
}
}
1.11 Delete Field
Endpoint:
DELETE /api/v1/e-events/drafts/{draftId}/attendee-questions/fields/{fieldId}
Response (200 OK):
{
"success": true,
"httpStatus": "OK",
"message": "Field deleted"
}
1.12 Reorder Fields
Endpoint:
POST /api/v1/e-events/drafts/{draftId}/attendee-questions/pages/{pageId}/fields/reorder
Request:
{
"orderedIds": [
"bb0e8400-e29b-41d4-a716-446655440006",
"990e8400-e29b-41d4-a716-446655440004",
"aa0e8400-e29b-41d4-a716-446655440005"
]
}
Response (200 OK):
{
"success": true,
"httpStatus": "OK",
"message": "Fields reordered"
}
Options Management (for DROPDOWN, RADIO, CHECKBOX)
1.13 Add Option
Endpoint:
POST /api/v1/e-events/drafts/{draftId}/attendee-questions/fields/{fieldId}/options
Request:
{
"label": "Social Media"
}
Response (201 Created):
{
"success": true,
"httpStatus": "CREATED",
"message": "Option added",
"data": {
"optionId": "220e8400-e29b-41d4-a716-446655440012",
"label": "Social Media",
"displayOrder": 1
}
}
1.14 Update Option
Endpoint:
PATCH /api/v1/e-events/drafts/{draftId}/attendee-questions/options/{optionId}
Request:
{
"label": "Social Media (Facebook, Instagram, etc.)"
}
Response (200 OK):
{
"success": true,
"httpStatus": "OK",
"message": "Option updated",
"data": {
"optionId": "220e8400-e29b-41d4-a716-446655440012",
"label": "Social Media (Facebook, Instagram, etc.)",
"displayOrder": 1
}
}
1.15 Delete Option
Endpoint:
DELETE /api/v1/e-events/drafts/{draftId}/attendee-questions/options/{optionId}
Response (200 OK):
{
"success": true,
"httpStatus": "OK",
"message": "Option deleted"
}
1.16 Reorder Options
Endpoint:
POST /api/v1/e-events/drafts/{draftId}/attendee-questions/fields/{fieldId}/options/reorder
Request:
{
"orderedIds": [
"220e8400-e29b-41d4-a716-446655440012",
"330e8400-e29b-41d4-a716-446655440013",
"440e8400-e29b-41d4-a716-446655440014"
]
}
Response (200 OK):
{
"success": true,
"httpStatus": "OK",
"message": "Options reordered"
}
PART 2: ATTENDEE ENDPOINTS (Public)
Base URL
/api/v1/e-events/{eventId}/attendee-questions
Note: These endpoints require the event to be PUBLISHED.
2.1 Get Questionnaire (First Page)
Endpoint:
GET /api/v1/e-events/{eventId}/attendee-questions
Response - No questionnaire configured:
{
"success": true,
"httpStatus": "OK",
"message": "No questionnaire for this event",
"data": {
"eventId": "660e8400-e29b-41d4-a716-446655440001",
"eventTitle": "Music Festival 2025",
"hasForm": false,
"registrationOpen": false,
"message": "No questionnaire for this event"
}
}
Response - Registration not yet open:
{
"success": true,
"httpStatus": "OK",
"message": "Registration opens on 2025-02-01",
"data": {
"eventId": "660e8400-e29b-41d4-a716-446655440001",
"eventTitle": "Music Festival 2025",
"hasForm": true,
"registrationOpen": false,
"message": "Registration opens on 2025-02-01",
"registrationOpensAt": "2025-02-01T09:00:00Z",
"registrationClosesAt": "2025-02-15T18:00:00Z",
"displayTime": "BEFORE_CHECKOUT",
"isRequired": true
}
}
Response - Registration closed:
{
"success": true,
"httpStatus": "OK",
"message": "Registration closed on 2025-02-15",
"data": {
"eventId": "660e8400-e29b-41d4-a716-446655440001",
"eventTitle": "Music Festival 2025",
"hasForm": true,
"registrationOpen": false,
"message": "Registration closed on 2025-02-15",
"registrationOpensAt": "2025-02-01T09:00:00Z",
"registrationClosesAt": "2025-02-15T18:00:00Z"
}
}
Response - Registration open (returns page 1):
{
"success": true,
"httpStatus": "OK",
"message": "Questionnaire retrieved",
"data": {
"eventId": "660e8400-e29b-41d4-a716-446655440001",
"eventTitle": "Music Festival 2025",
"hasForm": true,
"registrationOpen": true,
"registrationOpensAt": "2025-02-01T09:00:00Z",
"registrationClosesAt": "2025-02-15T18:00:00Z",
"displayTime": "BEFORE_CHECKOUT",
"isRequired": true,
"currentPage": 1,
"totalPages": 2,
"formTitle": "Attendee Questions - Music Festival 2025",
"formDescription": "Please complete this questionnaire",
"page": {
"pageId": "880e8400-e29b-41d4-a716-446655440003",
"title": "Personal Information",
"description": "Basic attendee details",
"displayOrder": 1,
"fields": [
{
"fieldId": "990e8400-e29b-41d4-a716-446655440004",
"type": "TEXT",
"label": "Emergency Contact Name",
"description": "Who should we contact in case of emergency?",
"placeholder": "Full name",
"displayOrder": 1,
"required": true,
"validation": {
"minLength": 2,
"maxLength": 100
},
"options": []
},
{
"fieldId": "aa0e8400-e29b-41d4-a716-446655440005",
"type": "PHONE",
"label": "Emergency Contact Phone",
"displayOrder": 2,
"required": true,
"options": []
},
{
"fieldId": "bb0e8400-e29b-41d4-a716-446655440006",
"type": "DROPDOWN",
"label": "T-Shirt Size",
"displayOrder": 3,
"required": true,
"options": [
{"optionId": "opt1", "label": "Small", "displayOrder": 1},
{"optionId": "opt2", "label": "Medium", "displayOrder": 2},
{"optionId": "opt3", "label": "Large", "displayOrder": 3},
{"optionId": "opt4", "label": "X-Large", "displayOrder": 4}
]
}
]
}
}
}
2.2 Get Specific Page
Endpoint:
GET /api/v1/e-events/{eventId}/attendee-questions/pages/{pageNumber}
Example:
GET /api/v1/e-events/660e8400-e29b-41d4-a716-446655440001/attendee-questions/pages/2
Response (200 OK):
{
"success": true,
"httpStatus": "OK",
"message": "Page 2 of 2",
"data": {
"eventId": "660e8400-e29b-41d4-a716-446655440001",
"eventTitle": "Music Festival 2025",
"hasForm": true,
"registrationOpen": true,
"currentPage": 2,
"totalPages": 2,
"page": {
"pageId": "cc0e8400-e29b-41d4-a716-446655440007",
"title": "Dietary Requirements",
"displayOrder": 2,
"fields": [
{
"fieldId": "dd0e8400-e29b-41d4-a716-446655440008",
"type": "CHECKBOX",
"label": "Dietary Restrictions",
"description": "Select all that apply",
"displayOrder": 1,
"required": false,
"options": [
{"optionId": "opt5", "label": "Vegetarian", "displayOrder": 1},
{"optionId": "opt6", "label": "Vegan", "displayOrder": 2},
{"optionId": "opt7", "label": "Gluten-free", "displayOrder": 3},
{"optionId": "opt8", "label": "Halal", "displayOrder": 4},
{"optionId": "opt9", "label": "Kosher", "displayOrder": 5}
]
},
{
"fieldId": "ee0e8400-e29b-41d4-a716-446655440009",
"type": "TEXTAREA",
"label": "Other Dietary Notes",
"placeholder": "Any allergies or special requirements?",
"displayOrder": 2,
"required": false
}
]
}
}
}
Error - Page not found:
{
"success": false,
"httpStatus": "NOT_FOUND",
"message": "Page not found. Valid pages: 1 to 2"
}
2.3 Save Page Answers (Auto-Save)
Saves answers for a single page. Validates ALL fields on the page before saving. If any field is invalid, nothing is saved.
Endpoint:
PATCH /api/v1/e-events/{eventId}/attendee-questions/responses/pages/{pageNumber}
Request:
{
"answers": {
"990e8400-e29b-41d4-a716-446655440004": {
"fieldId": "990e8400-e29b-41d4-a716-446655440004",
"value": "John Doe"
},
"aa0e8400-e29b-41d4-a716-446655440005": {
"fieldId": "aa0e8400-e29b-41d4-a716-446655440005",
"value": "+255712345678"
},
"bb0e8400-e29b-41d4-a716-446655440006": {
"fieldId": "bb0e8400-e29b-41d4-a716-446655440006",
"value": "Large"
}
}
}
Answer Format by Field Type:
Field Type
Value Format
Example
TEXT, TEXTAREA, EMAIL, PHONE, URL
string
"John Doe"
NUMBER, CURRENCY, RATING, SCALE, SLIDER
number
42 or 4.5
DATE
string (YYYY-MM-DD)
"2025-02-15"
TIME
string (HH:MM)
"14:30"
DATETIME
string (ISO)
"2025-02-15T14:30:00"
DROPDOWN, RADIO
string (selected label)
"Large"
CHECKBOX
array of strings
["Vegetarian", "Gluten-free"]
FILE
object
See below
File Upload Answer:
{
"fieldId": "file-field-id",
"value": null,
"fileUrl": "https://storage.example.com/uploads/id-doc.pdf",
"fileName": "id-doc.pdf",
"fileSize": 1048576,
"fileType": "application/pdf"
}
Response - Success (200 OK):
{
"success": true,
"httpStatus": "OK",
"message": "Page 1 saved",
"data": {
"eventId": "660e8400-e29b-41d4-a716-446655440001",
"pageNumber": 1,
"saved": true,
"savedAt": "2025-01-23T10:45:00Z",
"isValid": true,
"errors": [],
"totalFieldsOnPage": 3,
"answeredFieldsOnPage": 3,
"overallProgress": {
"totalPages": 2,
"completedPages": 1,
"totalFields": 5,
"answeredFields": 3,
"completionPercentage": 60
}
}
}
Response - Validation Failed (400 Bad Request):
{
"success": false,
"httpStatus": "BAD_REQUEST",
"message": "Validation failed - page not saved",
"data": {
"eventId": "660e8400-e29b-41d4-a716-446655440001",
"pageNumber": 1,
"saved": false,
"isValid": false,
"errors": [
{
"fieldId": "aa0e8400-e29b-41d4-a716-446655440005",
"fieldLabel": "Emergency Contact Phone",
"errorCode": "INVALID_PHONE",
"message": "Please enter a valid phone number"
},
{
"fieldId": "bb0e8400-e29b-41d4-a716-446655440006",
"fieldLabel": "T-Shirt Size",
"errorCode": "INVALID_OPTION",
"message": "Selected option is not valid"
}
],
"totalFieldsOnPage": 3,
"answeredFieldsOnPage": 3,
"overallProgress": {
"totalPages": 2,
"completedPages": 0,
"totalFields": 5,
"answeredFields": 0,
"completionPercentage": 0
}
}
}
Validation Error Codes:
Code
Description
REQUIRED
Required field is missing
INVALID_EMAIL
Invalid email format
INVALID_PHONE
Invalid phone number
INVALID_NUMBER
Not a valid number
INVALID_DATE
Invalid date format
INVALID_TIME
Invalid time format
INVALID_DATETIME
Invalid datetime format
INVALID_URL
Invalid URL format
INVALID_OPTION
Selected option not in list
INVALID_SELECTION
Invalid selection format
TOO_SHORT
Text too short (minLength)
TOO_LONG
Text too long (maxLength)
BELOW_MIN
Number below minimum
ABOVE_MAX
Number above maximum
DATE_TOO_EARLY
Date before minDate
DATE_TOO_LATE
Date after maxDate
TOO_FEW_SELECTIONS
Not enough checkboxes
TOO_MANY_SELECTIONS
Too many checkboxes
PATTERN_MISMATCH
Doesn't match regex
FILE_TOO_LARGE
File exceeds maxSizeMb
INVALID_FILE_TYPE
File type not accepted
2.4 Submit Final Response
Submits the form. No request body needed - validates all saved pages and submits if all valid.
Endpoint:
POST /api/v1/e-events/{eventId}/attendee-questions/responses/submit
Response - Success (200 OK):
{
"success": true,
"httpStatus": "OK",
"message": "Submission successful",
"data": {
"responseId": "550e8400-e29b-41d4-a716-446655440099",
"eventId": "660e8400-e29b-41d4-a716-446655440001",
"success": true,
"status": "SUBMITTED",
"submittedAt": "2025-01-23T10:50:00Z",
"pageValidations": [
{
"pageNumber": 1,
"pageTitle": "Personal Information",
"isValid": true,
"hasAnswers": true,
"totalFields": 3,
"answeredFields": 3,
"requiredFields": 3,
"requiredAnswered": 3,
"errors": []
},
{
"pageNumber": 2,
"pageTitle": "Dietary Requirements",
"isValid": true,
"hasAnswers": true,
"totalFields": 2,
"answeredFields": 1,
"requiredFields": 0,
"requiredAnswered": 0,
"errors": []
}
],
"totalPages": 2,
"validPages": 2,
"invalidPages": 0,
"allPagesValid": true
}
}
Response - Validation Failed (400 Bad Request):
{
"success": false,
"httpStatus": "BAD_REQUEST",
"message": "Validation failed - 1 page(s) have errors",
"data": {
"eventId": "660e8400-e29b-41d4-a716-446655440001",
"success": false,
"status": "DRAFT",
"pageValidations": [
{
"pageNumber": 1,
"pageTitle": "Personal Information",
"isValid": false,
"hasAnswers": true,
"totalFields": 3,
"answeredFields": 2,
"requiredFields": 3,
"requiredAnswered": 2,
"errors": [
{
"fieldId": "bb0e8400-e29b-41d4-a716-446655440006",
"fieldLabel": "T-Shirt Size",
"errorCode": "REQUIRED",
"message": "T-Shirt Size is required"
}
]
},
{
"pageNumber": 2,
"pageTitle": "Dietary Requirements",
"isValid": true,
"hasAnswers": false,
"totalFields": 2,
"answeredFields": 0,
"requiredFields": 0,
"requiredAnswered": 0,
"errors": []
}
],
"totalPages": 2,
"validPages": 1,
"invalidPages": 1,
"allPagesValid": false
}
}
Error - No draft found:
{
"success": false,
"httpStatus": "NOT_FOUND",
"message": "No draft found. Please save your answers first."
}
2.5 Get Submission Status
Endpoint:
GET /api/v1/e-events/{eventId}/attendee-questions/responses/status
Response - No submission started:
{
"success": true,
"httpStatus": "OK",
"message": "No submission started",
"data": {
"eventId": "660e8400-e29b-41d4-a716-446655440001",
"success": false,
"status": null,
"totalPages": 2,
"validPages": 0,
"invalidPages": 0,
"allPagesValid": false
}
}
Response - Draft in progress:
{
"success": true,
"httpStatus": "OK",
"message": "Status: DRAFT",
"data": {
"responseId": "550e8400-e29b-41d4-a716-446655440099",
"eventId": "660e8400-e29b-41d4-a716-446655440001",
"success": false,
"status": "DRAFT",
"submittedAt": null,
"pageValidations": [
{
"pageNumber": 1,
"pageTitle": "Personal Information",
"isValid": true,
"hasAnswers": true,
"totalFields": 3,
"answeredFields": 3,
"requiredFields": 3,
"requiredAnswered": 3,
"errors": []
},
{
"pageNumber": 2,
"pageTitle": "Dietary Requirements",
"isValid": true,
"hasAnswers": false,
"totalFields": 2,
"answeredFields": 0,
"requiredFields": 0,
"requiredAnswered": 0,
"errors": []
}
],
"totalPages": 2,
"validPages": 2,
"invalidPages": 0,
"allPagesValid": true
}
}
Response - Already submitted:
{
"success": true,
"httpStatus": "OK",
"message": "Status: SUBMITTED",
"data": {
"responseId": "550e8400-e29b-41d4-a716-446655440099",
"eventId": "660e8400-e29b-41d4-a716-446655440001",
"success": true,
"status": "SUBMITTED",
"submittedAt": "2025-01-23T10:50:00Z",
"totalPages": 2,
"validPages": 2,
"invalidPages": 0,
"allPagesValid": true
}
}
2.6 Withdraw Submission
Endpoint:
DELETE /api/v1/e-events/{eventId}/attendee-questions/responses
Response (200 OK):
{
"success": true,
"httpStatus": "OK",
"message": "Submission withdrawn"
}
PART 3: ANALYTICS ENDPOINTS (Organizer Only)
Base URL
/api/v1/e-events/{eventId}/attendee-questions/analytics
Note: Only the event organizer can access analytics.
3.1 Get Summary Statistics
Endpoint:
GET /api/v1/e-events/{eventId}/attendee-questions/analytics/summary
Response (200 OK):
{
"success": true,
"httpStatus": "OK",
"message": "Summary retrieved",
"data": {
"eventId": "660e8400-e29b-41d4-a716-446655440001",
"eventTitle": "Music Festival 2025",
"totalStarted": 250,
"totalDrafts": 45,
"totalSubmitted": 180,
"totalWithdrawn": 25,
"completionRate": 72.0,
"dropOffRate": 28.0,
"averageCompletionTimeSeconds": 185.5,
"fastestCompletionSeconds": 45,
"slowestCompletionSeconds": 890,
"submissionTrend": [
{"date": "2025-01-01", "count": 0},
{"date": "2025-01-02", "count": 5},
{"date": "2025-01-03", "count": 12},
{"date": "2025-01-04", "count": 8},
{"date": "2025-01-05", "count": 15},
{"date": "2025-01-06", "count": 22},
{"date": "2025-01-07", "count": 18}
],
"pageDropOff": [
{
"pageNumber": 1,
"pageTitle": "Personal Information",
"started": 250,
"completed": 220,
"dropOffRate": 12.0
},
{
"pageNumber": 2,
"pageTitle": "Dietary Requirements",
"started": 220,
"completed": 180,
"dropOffRate": 18.2
}
],
"firstSubmissionAt": "2025-01-02T09:15:00",
"lastSubmissionAt": "2025-01-23T10:50:00",
"generatedAt": "2025-01-23T11:00:00"
}
}
3.2 Get All Fields Analytics
Endpoint:
GET /api/v1/e-events/{eventId}/attendee-questions/analytics/fields
Response (200 OK):
{
"success": true,
"httpStatus": "OK",
"message": "Fields analytics retrieved",
"data": {
"eventId": "660e8400-e29b-41d4-a716-446655440001",
"totalResponses": 180,
"fields": [
{
"fieldId": "990e8400-e29b-41d4-a716-446655440004",
"label": "Emergency Contact Name",
"type": "TEXT",
"pageNumber": 1,
"required": true,
"responseCount": 180,
"skippedCount": 0,
"responseRate": 100.0,
"textStats": {
"averageLength": 15,
"minLength": 5,
"maxLength": 45,
"commonWords": ["john", "jane", "mary", "james", "david"]
}
},
{
"fieldId": "bb0e8400-e29b-41d4-a716-446655440006",
"label": "T-Shirt Size",
"type": "DROPDOWN",
"pageNumber": 1,
"required": true,
"responseCount": 180,
"skippedCount": 0,
"responseRate": 100.0,
"optionBreakdown": [
{"value": "Medium", "count": 65, "percentage": 36.1},
{"value": "Large", "count": 58, "percentage": 32.2},
{"value": "Small", "count": 35, "percentage": 19.4},
{"value": "X-Large", "count": 22, "percentage": 12.2}
]
},
{
"fieldId": "dd0e8400-e29b-41d4-a716-446655440008",
"label": "Dietary Restrictions",
"type": "CHECKBOX",
"pageNumber": 2,
"required": false,
"responseCount": 95,
"skippedCount": 85,
"responseRate": 52.8,
"optionBreakdown": [
{"value": "Vegetarian", "count": 42, "percentage": 44.2},
{"value": "Gluten-free", "count": 28, "percentage": 29.5},
{"value": "Vegan", "count": 18, "percentage": 18.9},
{"value": "Halal", "count": 12, "percentage": 12.6},
{"value": "Kosher", "count": 5, "percentage": 5.3}
]
}
]
}
}
3.3 Get Single Field Analytics
Endpoint:
GET /api/v1/e-events/{eventId}/attendee-questions/analytics/fields/{fieldId}?page=0&size=20
Response (200 OK):
{
"success": true,
"httpStatus": "OK",
"message": "Field analytics retrieved",
"data": {
"eventId": "660e8400-e29b-41d4-a716-446655440001",
"fieldId": "bb0e8400-e29b-41d4-a716-446655440006",
"label": "T-Shirt Size",
"type": "DROPDOWN",
"required": true,
"totalResponses": 180,
"responseCount": 180,
"skippedCount": 0,
"responseRate": 100.0,
"optionBreakdown": [
{"value": "Medium", "count": 65, "percentage": 36.1},
{"value": "Large", "count": 58, "percentage": 32.2},
{"value": "Small", "count": 35, "percentage": 19.4},
{"value": "X-Large", "count": 22, "percentage": 12.2}
],
"responses": [
{
"responseId": "resp-001",
"value": "Large",
"submittedAt": "2025-01-23T10:50:00"
},
{
"responseId": "resp-002",
"value": "Medium",
"submittedAt": "2025-01-23T10:48:00"
}
],
"totalResponseCount": 180,
"page": 0,
"pageSize": 20
}
}
3.4 Get All Responses (Spreadsheet View)
Endpoint:
GET /api/v1/e-events/{eventId}/attendee-questions/analytics/responses?page=0&size=20
Response (200 OK):
{
"success": true,
"httpStatus": "OK",
"message": "Responses retrieved",
"data": {
"eventId": "660e8400-e29b-41d4-a716-446655440001",
"totalResponses": 180,
"page": 0,
"pageSize": 20,
"totalPages": 9,
"columns": [
{"fieldId": "990e8400-e29b-41d4-a716-446655440004", "label": "Emergency Contact Name", "type": "TEXT", "pageNumber": 1},
{"fieldId": "aa0e8400-e29b-41d4-a716-446655440005", "label": "Emergency Contact Phone", "type": "PHONE", "pageNumber": 1},
{"fieldId": "bb0e8400-e29b-41d4-a716-446655440006", "label": "T-Shirt Size", "type": "DROPDOWN", "pageNumber": 1},
{"fieldId": "dd0e8400-e29b-41d4-a716-446655440008", "label": "Dietary Restrictions", "type": "CHECKBOX", "pageNumber": 2},
{"fieldId": "ee0e8400-e29b-41d4-a716-446655440009", "label": "Other Dietary Notes", "type": "TEXTAREA", "pageNumber": 2}
],
"responses": [
{
"responseId": "resp-001",
"submittedById": "user-001",
"submittedByName": "kibuti",
"submittedByEmail": "kibuti@example.com",
"status": "SUBMITTED",
"startedAt": "2025-01-23T10:40:00",
"submittedAt": "2025-01-23T10:50:00",
"completionTimeSeconds": 600,
"answers": {
"990e8400-e29b-41d4-a716-446655440004": "John Doe",
"aa0e8400-e29b-41d4-a716-446655440005": "+255712345678",
"bb0e8400-e29b-41d4-a716-446655440006": "Large",
"dd0e8400-e29b-41d4-a716-446655440008": ["Vegetarian", "Gluten-free"],
"ee0e8400-e29b-41d4-a716-446655440009": "No nuts please"
}
},
{
"responseId": "resp-002",
"submittedById": "user-002",
"submittedByName": "john_doe",
"submittedByEmail": "john@example.com",
"status": "SUBMITTED",
"startedAt": "2025-01-23T10:30:00",
"submittedAt": "2025-01-23T10:45:00",
"completionTimeSeconds": 900,
"answers": {
"990e8400-e29b-41d4-a716-446655440004": "Jane Smith",
"aa0e8400-e29b-41d4-a716-446655440005": "+255798765432",
"bb0e8400-e29b-41d4-a716-446655440006": "Medium",
"dd0e8400-e29b-41d4-a716-446655440008": null,
"ee0e8400-e29b-41d4-a716-446655440009": null
}
}
]
}
}
3.5 Export to CSV
Endpoint:
GET /api/v1/e-events/{eventId}/attendee-questions/analytics/export/csv
Response: Downloads a CSV file
CSV Content:
Response ID,Submitted By,Email,Submitted At,Completion Time (seconds),Emergency Contact Name,Emergency Contact Phone,T-Shirt Size,Dietary Restrictions,Other Dietary Notes
resp-001,kibuti,kibuti@example.com,2025-01-23T10:50:00,600,John Doe,+255712345678,Large,Vegetarian; Gluten-free,No nuts please
resp-002,john_doe,john@example.com,2025-01-23T10:45:00,900,Jane Smith,+255798765432,Medium,,
3.6 Export to Excel
Endpoint:
GET /api/v1/e-events/{eventId}/attendee-questions/analytics/export/excel
Response: Downloads an Excel (.xlsx) file
PART 4: COMPLETE ENDPOINTS REFERENCE
Organizer Endpoints (Draft Events)
Method
Endpoint
Description
PUT
/drafts/{draftId}/attendee-questions
Enable questionnaire
PATCH
/drafts/{draftId}/attendee-questions
Update settings
GET
/drafts/{draftId}/attendee-questions
Get with full form
DELETE
/drafts/{draftId}/attendee-questions
Disable (delete)
POST
/drafts/{draftId}/attendee-questions/pages
Add page
PATCH
/drafts/{draftId}/attendee-questions/pages/{pageId}
Update page
DELETE
/drafts/{draftId}/attendee-questions/pages/{pageId}
Delete page
POST
/drafts/{draftId}/attendee-questions/pages/reorder
Reorder pages
POST
/drafts/{draftId}/attendee-questions/pages/{pageId}/fields
Add field
PATCH
/drafts/{draftId}/attendee-questions/fields/{fieldId}
Update field
DELETE
/drafts/{draftId}/attendee-questions/fields/{fieldId}
Delete field
POST
/drafts/{draftId}/attendee-questions/pages/{pageId}/fields/reorder
Reorder fields
POST
/drafts/{draftId}/attendee-questions/fields/{fieldId}/options
Add option
PATCH
/drafts/{draftId}/attendee-questions/options/{optionId}
Update option
DELETE
/drafts/{draftId}/attendee-questions/options/{optionId}
Delete option
POST
/drafts/{draftId}/attendee-questions/fields/{fieldId}/options/reorder
Reorder options
Attendee Endpoints (Published Events)
Method
Endpoint
Description
GET
/{eventId}/attendee-questions
Get form (page 1)
GET
/{eventId}/attendee-questions/pages/{n}
Get specific page
PATCH
/{eventId}/attendee-questions/responses/pages/{n}
Save page (auto-save)
POST
/{eventId}/attendee-questions/responses/submit
Submit (no body)
GET
/{eventId}/attendee-questions/responses/status
Get my status
DELETE
/{eventId}/attendee-questions/responses
Withdraw
Analytics Endpoints (Organizer Only)
Method
Endpoint
Description
GET
/{eventId}/attendee-questions/analytics/summary
Overall stats
GET
/{eventId}/attendee-questions/analytics/fields
All fields breakdown
GET
/{eventId}/attendee-questions/analytics/fields/{fieldId}
Single field detail
GET
/{eventId}/attendee-questions/analytics/responses
Spreadsheet view
GET
/{eventId}/attendee-questions/analytics/export/csv
Download CSV
GET
/{eventId}/attendee-questions/analytics/export/excel
Download Excel
PART 5: INSOMNIA TESTING GUIDE
Setup Environment Variables
base_url: http://localhost:8080/api/v1
jwt_token:
draft_id:
event_id:
page_id:
field_id:
option_id:
Testing Flow
Step 1: Create Event Draft
POST {{base_url}}/e-events/drafts
Authorization: Bearer {{jwt_token}}
Content-Type: application/json
{
"title": "Test Music Festival 2025",
"categoryId": "{{category_id}}",
"eventFormat": "IN_PERSON",
"description": "Test event for questionnaire"
}
Step 2: Enable Attendee Questions
PUT {{base_url}}/e-events/drafts/{{draft_id}}/attendee-questions
Authorization: Bearer {{jwt_token}}
Content-Type: application/json
{
"displayTime": "BEFORE_CHECKOUT",
"isRequiredOnline": true,
"applyToAtDoor": false
}
Step 3: Get Questionnaire (see default page)
GET {{base_url}}/e-events/drafts/{{draft_id}}/attendee-questions
Authorization: Bearer {{jwt_token}}
Step 4: Add Text Field
POST {{base_url}}/e-events/drafts/{{draft_id}}/attendee-questions/pages/{{page_id}}/fields
Authorization: Bearer {{jwt_token}}
Content-Type: application/json
{
"type": "TEXT",
"label": "Emergency Contact Name",
"placeholder": "Full name",
"required": true,
"validation": {
"minLength": 2,
"maxLength": 100
}
}
Step 5: Add Dropdown Field
POST {{base_url}}/e-events/drafts/{{draft_id}}/attendee-questions/pages/{{page_id}}/fields
Authorization: Bearer {{jwt_token}}
Content-Type: application/json
{
"type": "DROPDOWN",
"label": "T-Shirt Size",
"required": true
}
Step 6: Add Options to Dropdown
POST {{base_url}}/e-events/drafts/{{draft_id}}/attendee-questions/fields/{{field_id}}/options
Authorization: Bearer {{jwt_token}}
Content-Type: application/json
{"label": "Small"}
Repeat for: Medium, Large, X-Large
Step 7: Publish Event
POST {{base_url}}/e-events/drafts/{{draft_id}}/publish
Authorization: Bearer {{jwt_token}}
Step 8: (As Attendee) Get Questionnaire
GET {{base_url}}/e-events/{{event_id}}/attendee-questions
Authorization: Bearer {{attendee_token}}
Step 9: (As Attendee) Save Page 1
PATCH {{base_url}}/e-events/{{event_id}}/attendee-questions/responses/pages/1
Authorization: Bearer {{attendee_token}}
Content-Type: application/json
{
"answers": {
"{{text_field_id}}": {
"fieldId": "{{text_field_id}}",
"value": "John Doe"
},
"{{dropdown_field_id}}": {
"fieldId": "{{dropdown_field_id}}",
"value": "Large"
}
}
}
Step 10: (As Attendee) Submit
POST {{base_url}}/e-events/{{event_id}}/attendee-questions/responses/submit
Authorization: Bearer {{attendee_token}}
Step 11: (As Organizer) View Analytics
GET {{base_url}}/e-events/{{event_id}}/attendee-questions/analytics/summary
Authorization: Bearer {{jwt_token}}
Step 12: (As Organizer) Export CSV
GET {{base_url}}/e-events/{{event_id}}/attendee-questions/analytics/export/csv
Authorization: Bearer {{jwt_token}}
This guide covers the complete Attendee Questions API. Ready to implement and test!