Event Applicant Form API

Author: Josh S. Sakweli, Backend Lead Team
Last Updated: 2026-02-03
Version: v1.0

Base URL: https://api.nextgate.com/api/v1/e-events/applicant-form

Short Description: The Event Applicant Form API allows event organizers to create customizable questionnaires for attendees. Organizers can build multi-page forms with various field types, configure when forms appear in the registration flow (before or after checkout), and view submission analytics. Attendees can fill out forms progressively with draft-saving capabilities.

Hints:

Forms are linked to events via the event ID - one form per event
Form responses are automatically validated based on field configurations
Attendees can save progress and return later before final submission
Once submitted, responses are read-only (no editing allowed)
Forms must be enabled before pages/fields can be added
Form Builder handles all validation, file uploads, and multi-page logic internally
Display time settings: BEFORE_CHECKOUT (required before ticket purchase) or AFTER_CHECKOUT (optional post-purchase)

Event Registration Flow Diagram

Event Creation & Form Setup (Organizer)
│
├─── 1. Create Event
│    └─── Event published and live
│
├─── 2. Enable Applicant Form
│    ├─── Configure display time (BEFORE_CHECKOUT | AFTER_CHECKOUT)
│    ├─── Set if required for online purchases
│    └─── Set if applies to at-door attendees
│
├─── 3. Build Form Structure
│    ├─── Add pages
│    ├─── Add fields to pages
│    └─── Add options to choice fields
│
└─── 4. Form is Live
     │
     ▼
Attendee Registration Flow
│
├─── IF BEFORE_CHECKOUT:
│    ├─── 1. Attendee views event
│    ├─── 2. Attendee starts form submission
│    ├─── 3. Attendee fills form (can save draft)
│    ├─── 4. Attendee submits form ✓
│    ├─── 5. Attendee proceeds to checkout
│    └─── 6. Attendee purchases ticket
│
└─── IF AFTER_CHECKOUT:
     ├─── 1. Attendee views event
     ├─── 2. Attendee purchases ticket
     ├─── 3. Attendee receives form link (email/notification)
     ├─── 4. Attendee starts form submission
     ├─── 5. Attendee fills form (can save draft)
     └─── 6. Attendee submits form ✓
     
Organizer Analytics
│
├─── View all responses
├─── View individual response details
└─── View form analytics (completion rates, field statistics)

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": "2026-02-03T10:30:45",
  "data": {
    // Actual response data goes here
  }
}

Error Response Structure

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Error description",
  "action_time": "2026-02-03T10:30:45",
  "data": "Error description"
}

Standard Response Fields

Field	Type	Description
`success`	boolean	Always `true` for successful operations, `false` for errors
`httpStatus`	string	HTTP status name (OK, CREATED, BAD_REQUEST, NOT_FOUND, etc.)
`message`	string	Human-readable message describing the operation result
`action_time`	string	ISO 8601 timestamp of when the response was generated
`data`	object/string	Response payload for success, error details for failures

HTTP Method Badge Standards

GET - GET - Green (Read-only operations)
POST - POST - Blue (Create new resources)
PUT - PUT - Yellow (Update entire resource)
DELETE - DELETE - Red (Remove resources)

Endpoints

1. Enable Applicant Form

Purpose: Enables the applicant form feature for an event, creating a new form and linking it to the event.

Endpoint: POST /events/{eventId}/enable

Access Level: 🔒 Protected (Event Organizer Only)

Authentication: Bearer Token Required

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication
Content-Type	string	Yes	Must be `application/json`

Path Parameters:

Parameter	Type	Required	Description	Validation
eventId	UUID	Yes	Unique identifier of the event	Valid UUID format

Request JSON Sample:

{
  "displayTime": "BEFORE_CHECKOUT",
  "isRequiredOnline": true,
  "applyToAtDoor": false
}

Request Body Parameters:

Parameter	Type	Required	Description	Validation
displayTime	string	No	When to show the form	enum: BEFORE_CHECKOUT, AFTER_CHECKOUT (default: BEFORE_CHECKOUT)
isRequiredOnline	boolean	No	Whether form is required for online purchases	default: false
applyToAtDoor	boolean	No	Whether form applies to at-door attendees	default: false

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "CREATED",
  "message": "Applicant form enabled",
  "action_time": "2026-02-03T10:30:45",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "event": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "title": "Tech Conference 2026"
    },
    "formId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "displayTime": "BEFORE_CHECKOUT",
    "isRequiredOnline": true,
    "applyToAtDoor": false,
    "createdAt": "2026-02-03T10:30:45Z",
    "updatedAt": "2026-02-03T10:30:45Z"
  }
}

Success Response Fields:

Field	Description
id	Unique identifier of the form configuration
event	Event object containing event ID and title
formId	Internal form ID used by Form Builder
displayTime	When the form is shown to attendees
isRequiredOnline	Whether form must be completed for online purchases
applyToAtDoor	Whether form applies to walk-in attendees
createdAt	Timestamp when form was enabled
updatedAt	Timestamp of last update

Error Response Examples:

Form Already Enabled (403):

{
  "success": false,
  "httpStatus": "FORBIDDEN",
  "message": "Form already enabled",
  "action_time": "2026-02-03T10:30:45",
  "data": "Form already enabled"
}

Event Not Found (404):

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Event not found",
  "action_time": "2026-02-03T10:30:45",
  "data": "Event not found"
}

Not Event Organizer (403):

{
  "success": false,
  "httpStatus": "FORBIDDEN",
  "message": "Only organizer can manage form",
  "action_time": "2026-02-03T10:30:45",
  "data": "Only organizer can manage form"
}

2. Update Form Settings

Purpose: Updates the display time and requirement settings for an existing applicant form.

Endpoint: PUT /events/{eventId}/settings

Access Level: 🔒 Protected (Event Organizer Only)

Authentication: Bearer Token Required

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication
Content-Type	string	Yes	Must be `application/json`

Path Parameters:

Parameter	Type	Required	Description	Validation
eventId	UUID	Yes	Unique identifier of the event	Valid UUID format

Request JSON Sample:

{
  "displayTime": "AFTER_CHECKOUT",
  "isRequiredOnline": false,
  "applyToAtDoor": true
}

Request Body Parameters:

Parameter	Type	Required	Description	Validation
displayTime	string	No	When to show the form	enum: BEFORE_CHECKOUT, AFTER_CHECKOUT
isRequiredOnline	boolean	No	Whether form is required for online purchases	true or false
applyToAtDoor	boolean	No	Whether form applies to at-door attendees	true or false

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Form settings updated",
  "action_time": "2026-02-03T10:35:22",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "event": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "title": "Tech Conference 2026"
    },
    "formId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "displayTime": "AFTER_CHECKOUT",
    "isRequiredOnline": false,
    "applyToAtDoor": true,
    "createdAt": "2026-02-03T10:30:45Z",
    "updatedAt": "2026-02-03T10:35:22Z"
  }
}

Error Response Examples:

Form Not Enabled (404):

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Form not enabled",
  "action_time": "2026-02-03T10:35:22",
  "data": "Form not enabled"
}

3. Disable Applicant Form

Purpose: Disables and removes the applicant form from an event, deleting all form structure and responses.

Endpoint: DELETE /events/{eventId}/disable

Access Level: 🔒 Protected (Event Organizer Only)

Authentication: Bearer Token Required

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Path Parameters:

Parameter	Type	Required	Description	Validation
eventId	UUID	Yes	Unique identifier of the event	Valid UUID format

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Applicant form disabled",
  "action_time": "2026-02-03T10:40:15"
}

Error Response Examples:

Form Not Enabled (404):

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Form not enabled",
  "action_time": "2026-02-03T10:40:15",
  "data": "Form not enabled"
}

4. Add Page to Form

Purpose: Creates a new page in the applicant form with a title, description, and optional action button text.

Endpoint: POST /events/{eventId}/pages

Access Level: 🔒 Protected (Event Organizer Only)

Authentication: Bearer Token Required

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication
Content-Type	string	Yes	Must be `application/json`

Path Parameters:

Parameter	Type	Required	Description	Validation
eventId	UUID	Yes	Unique identifier of the event	Valid UUID format

Request JSON Sample:

{
  "title": "Personal Information",
  "description": "Please provide your basic details",
  "displayOrder": 1,
  "actionButtonText": "Next"
}

Request Body Parameters:

Parameter	Type	Required	Description	Validation
title	string	Yes	Page title shown to attendees	Min: 1, Max: 200 characters
description	string	No	Optional description text	Max: 1000 characters
displayOrder	integer	No	Order in which page appears	Auto-assigned if not provided
actionButtonText	string	No	Text for next/submit button	Max: 50 characters (default: "Next")

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "CREATED",
  "message": "Page added",
  "action_time": "2026-02-03T10:45:30",
  "data": {
    "pageId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "title": "Personal Information",
    "description": "Please provide your basic details",
    "displayOrder": 1,
    "actionButtonText": "Next",
    "fields": []
  }
}

Success Response Fields:

Field	Description
pageId	Unique identifier of the created page
title	Page title
description	Page description
displayOrder	Position of page in form sequence
actionButtonText	Button text for this page
fields	Array of fields on this page (empty for new page)

5. Update Page

Purpose: Updates the title, description, display order, or action button text of an existing page.

Endpoint: PUT /events/{eventId}/pages/{pageId}

Access Level: 🔒 Protected (Event Organizer Only)

Authentication: Bearer Token Required

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication
Content-Type	string	Yes	Must be `application/json`

Path Parameters:

Parameter	Type	Required	Description	Validation
eventId	UUID	Yes	Unique identifier of the event	Valid UUID format
pageId	UUID	Yes	Unique identifier of the page	Valid UUID format

Request JSON Sample:

{
  "title": "Contact Details",
  "description": "How can we reach you?",
  "displayOrder": 2,
  "actionButtonText": "Continue"
}

Request Body Parameters:

Parameter	Type	Required	Description	Validation
title	string	No	Updated page title	Min: 1, Max: 200 characters
description	string	No	Updated description	Max: 1000 characters
displayOrder	integer	No	Updated display order	Positive integer
actionButtonText	string	No	Updated button text	Max: 50 characters

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Page updated",
  "action_time": "2026-02-03T10:50:12",
  "data": {
    "pageId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "title": "Contact Details",
    "description": "How can we reach you?",
    "displayOrder": 2,
    "actionButtonText": "Continue",
    "fields": []
  }
}

6. Delete Page

Purpose: Removes a page from the form, including all fields on that page.

Endpoint: DELETE /events/{eventId}/pages/{pageId}

Access Level: 🔒 Protected (Event Organizer Only)

Authentication: Bearer Token Required

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Path Parameters:

Parameter	Type	Required	Description	Validation
eventId	UUID	Yes	Unique identifier of the event	Valid UUID format
pageId	UUID	Yes	Unique identifier of the page	Valid UUID format

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Page deleted",
  "action_time": "2026-02-03T11:00:45"
}

Error Response Examples:

Page Not Found (404):

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Page not found",
  "action_time": "2026-02-03T11:00:45",
  "data": "Page not found"
}

7. Add Field to Page

Purpose: Creates a new form field on a specific page with validation rules and configuration.

Endpoint: POST /events/{eventId}/pages/{pageId}/fields

Access Level: 🔒 Protected (Event Organizer Only)

Authentication: Bearer Token Required

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication
Content-Type	string	Yes	Must be `application/json`

Path Parameters:

Parameter	Type	Required	Description	Validation
eventId	UUID	Yes	Unique identifier of the event	Valid UUID format
pageId	UUID	Yes	Unique identifier of the page	Valid UUID format

Request JSON Sample:

{
  "type": "EMAIL",
  "label": "Email Address",
  "description": "We'll use this to send you updates",
  "placeholder": "you@example.com",
  "displayOrder": 1,
  "required": true,
  "validation": {
    "min": null,
    "max": null,
    "pattern": null,
    "allowedFileTypes": null,
    "maxFileSize": null
  }
}

Request Body Parameters:

Parameter	Type	Required	Description	Validation
type	string	Yes	Field type	enum: TEXT, TEXTAREA, EMAIL, PHONE, NUMBER, DATE, DROPDOWN, RADIO, CHECKBOX, FILE, URL, CURRENCY, RATING, SCALE, SLIDER, SECTION_HEADER, PARAGRAPH
label	string	Yes	Field label shown to users	Min: 1, Max: 200 characters
description	string	No	Help text for the field	Max: 500 characters
placeholder	string	No	Placeholder text in input	Max: 100 characters
displayOrder	integer	No	Order within page	Auto-assigned if not provided
required	boolean	No	Whether field is mandatory	default: false
validation	object	No	Validation rules object	See validation object structure

Validation Object Structure:

Parameter	Type	Description	Used For
min	integer	Minimum value/length	NUMBER, TEXT, TEXTAREA fields
max	integer	Maximum value/length	NUMBER, TEXT, TEXTAREA fields
pattern	string	Regex pattern for validation	TEXT fields
allowedFileTypes	array	Allowed file extensions	FILE fields (e.g., ["pdf", "jpg"])
maxFileSize	long	Max file size in bytes	FILE fields

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "CREATED",
  "message": "Field added",
  "action_time": "2026-02-03T11:05:20",
  "data": {
    "fieldId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "type": "EMAIL",
    "label": "Email Address",
    "description": "We'll use this to send you updates",
    "placeholder": "you@example.com",
    "displayOrder": 1,
    "required": true,
    "validation": {
      "min": null,
      "max": null,
      "pattern": null,
      "allowedFileTypes": null,
      "maxFileSize": null
    },
    "options": []
  }
}

Success Response Fields:

Field	Description
fieldId	Unique identifier of the created field
type	Field type
label	Field label
description	Help text
placeholder	Placeholder text
displayOrder	Position within page
required	Whether field is mandatory
validation	Validation rules applied to this field
options	Array of options (empty for non-choice fields)

8. Update Field

Purpose: Updates properties of an existing field including label, validation rules, and requirements.

Endpoint: PUT /events/{eventId}/fields/{fieldId}

Access Level: 🔒 Protected (Event Organizer Only)

Authentication: Bearer Token Required

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication
Content-Type	string	Yes	Must be `application/json`

Path Parameters:

Parameter	Type	Required	Description	Validation
eventId	UUID	Yes	Unique identifier of the event	Valid UUID format
fieldId	UUID	Yes	Unique identifier of the field	Valid UUID format

Request JSON Sample:

{
  "label": "Business Email",
  "description": "Please use your company email",
  "placeholder": "name@company.com",
  "required": true,
  "validation": {
    "max": 100
  }
}

Request Body Parameters:

Parameter	Type	Required	Description	Validation
label	string	No	Updated field label	Min: 1, Max: 200 characters
description	string	No	Updated help text	Max: 500 characters
placeholder	string	No	Updated placeholder	Max: 100 characters
displayOrder	integer	No	Updated display order	Positive integer
required	boolean	No	Updated required status	true or false
validation	object	No	Updated validation rules	See validation object structure

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Field updated",
  "action_time": "2026-02-03T11:10:30",
  "data": {
    "fieldId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "type": "EMAIL",
    "label": "Business Email",
    "description": "Please use your company email",
    "placeholder": "name@company.com",
    "displayOrder": 1,
    "required": true,
    "validation": {
      "min": null,
      "max": 100,
      "pattern": null,
      "allowedFileTypes": null,
      "maxFileSize": null
    },
    "options": []
  }
}

9. Delete Field

Purpose: Removes a field from the form (soft delete - field data preserved in existing responses).

Endpoint: DELETE /events/{eventId}/fields/{fieldId}

Access Level: 🔒 Protected (Event Organizer Only)

Authentication: Bearer Token Required

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Path Parameters:

Parameter	Type	Required	Description	Validation
eventId	UUID	Yes	Unique identifier of the event	Valid UUID format
fieldId	UUID	Yes	Unique identifier of the field	Valid UUID format

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Field deleted",
  "action_time": "2026-02-03T11:15:45"
}

10. Add Option to Field

Purpose: Adds a choice option to dropdown, radio, or checkbox fields.

Endpoint: POST /events/{eventId}/fields/{fieldId}/options

Access Level: 🔒 Protected (Event Organizer Only)

Authentication: Bearer Token Required

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication
Content-Type	string	Yes	Must be `application/json`

Path Parameters:

Parameter	Type	Required	Description	Validation
eventId	UUID	Yes	Unique identifier of the event	Valid UUID format
fieldId	UUID	Yes	Unique identifier of the field	Valid UUID format (must be DROPDOWN, RADIO, or CHECKBOX type)

Request JSON Sample:

{
  "label": "Software Developer",
  "displayOrder": 1
}

Request Body Parameters:

Parameter	Type	Required	Description	Validation
label	string	Yes	Option text shown to users	Min: 1, Max: 200 characters
displayOrder	integer	No	Order in option list	Auto-assigned if not provided

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "CREATED",
  "message": "Option added",
  "action_time": "2026-02-03T11:20:10",
  "data": {
    "optionId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "label": "Software Developer",
    "displayOrder": 1
  }
}

Error Response Examples:

Invalid Field Type (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Options can only be added to DROPDOWN, RADIO, or CHECKBOX fields",
  "action_time": "2026-02-03T11:20:10",
  "data": "Options can only be added to DROPDOWN, RADIO, or CHECKBOX fields"
}

11. Update Option

Purpose: Updates the label or display order of an existing option.

Endpoint: PUT /events/{eventId}/options/{optionId}

Access Level: 🔒 Protected (Event Organizer Only)

Authentication: Bearer Token Required

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication
Content-Type	string	Yes	Must be `application/json`

Path Parameters:

Parameter	Type	Required	Description	Validation
eventId	UUID	Yes	Unique identifier of the event	Valid UUID format
optionId	UUID	Yes	Unique identifier of the option	Valid UUID format

Request JSON Sample:

{
  "label": "Senior Software Developer",
  "displayOrder": 2
}

Request Body Parameters:

Parameter	Type	Required	Description	Validation
label	string	No	Updated option text	Min: 1, Max: 200 characters
displayOrder	integer	No	Updated display order	Positive integer

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Option updated",
  "action_time": "2026-02-03T11:25:33",
  "data": {
    "optionId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "label": "Senior Software Developer",
    "displayOrder": 2
  }
}

12. Delete Option

Purpose: Removes an option from a choice field.

Endpoint: DELETE /events/{eventId}/options/{optionId}

Access Level: 🔒 Protected (Event Organizer Only)

Authentication: Bearer Token Required

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Path Parameters:

Parameter	Type	Required	Description	Validation
eventId	UUID	Yes	Unique identifier of the event	Valid UUID format
optionId	UUID	Yes	Unique identifier of the option	Valid UUID format

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Option deleted",
  "action_time": "2026-02-03T11:30:20"
}

13. Start Form Submission

Purpose: Initializes a new form response for an attendee, creating a draft they can save and return to.

Endpoint: POST /events/{eventId}/start

Access Level: 🔒 Protected (Authenticated Attendee)

Authentication: Bearer Token Required

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Path Parameters:

Parameter	Type	Required	Description	Validation
eventId	UUID	Yes	Unique identifier of the event	Valid UUID format

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Form submission started",
  "action_time": "2026-02-03T11:35:15",
  "data": {
    "responseId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "formId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "submittedBy": "john.doe@example.com",
    "status": "DRAFT",
    "completedPageIds": [],
    "currentPageIndex": 0,
    "startedAt": "2026-02-03T11:35:15Z",
    "submittedAt": null,
    "completionTimeSeconds": null,
    "answers": []
  }
}

Success Response Fields:

Field	Description
responseId	Unique identifier of this submission
formId	ID of the form being filled
submittedBy	Email/username of the attendee
status	Current status (DRAFT or SUBMITTED)
completedPageIds	Array of page IDs that have been completed
currentPageIndex	Zero-based index of current page
startedAt	When submission was started
submittedAt	When submission was finalized (null for drafts)
completionTimeSeconds	Time taken to complete (null for drafts)
answers	Array of answers provided so far

Error Response Examples:

Event Not Published (404):

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Event not available",
  "action_time": "2026-02-03T11:35:15",
  "data": "Event not available"
}

Registration Closed (403):

{
  "success": false,
  "httpStatus": "FORBIDDEN",
  "message": "Registration closed",
  "action_time": "2026-02-03T11:35:15",
  "data": "Registration closed"
}

14. Get My Response

Purpose: Retrieves the current user's form response (draft or submitted) for viewing or continuing.

Endpoint: GET /events/{eventId}/my-response

Access Level: 🔒 Protected (Authenticated Attendee)

Authentication: Bearer Token Required

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Path Parameters:

Parameter	Type	Required	Description	Validation
eventId	UUID	Yes	Unique identifier of the event	Valid UUID format

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Response retrieved",
  "action_time": "2026-02-03T11:40:22",
  "data": {
    "responseId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "formId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "submittedBy": "john.doe@example.com",
    "status": "DRAFT",
    "completedPageIds": ["9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"],
    "currentPageIndex": 1,
    "startedAt": "2026-02-03T11:35:15Z",
    "submittedAt": null,
    "completionTimeSeconds": null,
    "answers": [
      {
        "answerId": "ans-001",
        "fieldId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "fieldLabel": "Email Address",
        "fieldType": "EMAIL",
        "fieldDeleted": false,
        "value": "john.doe@example.com",
        "answeredAt": "2026-02-03T11:36:30Z",
        "fileUrl": null,
        "fileName": null,
        "fileSize": null,
        "fileType": null
      }
    ]
  }
}

Error Response Examples:

No Response Found (404):

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "No response found",
  "action_time": "2026-02-03T11:40:22",
  "data": "No response found"
}

15. Save Page Answers

Purpose: Saves answers for a specific page in draft mode (allows partial completion and return later).

Endpoint: PUT /events/{eventId}/pages/{pageId}/save

Access Level: 🔒 Protected (Authenticated Attendee)

Authentication: Bearer Token Required

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication
Content-Type	string	Yes	Must be `application/json`

Path Parameters:

Parameter	Type	Required	Description	Validation
eventId	UUID	Yes	Unique identifier of the event	Valid UUID format
pageId	UUID	Yes	Unique identifier of the page	Valid UUID format

Request JSON Sample:

{
  "3fa85f64-5717-4562-b3fc-2c963f66afa6": {
    "value": "john.doe@example.com",
    "fileUrl": null,
    "fileName": null,
    "fileSize": null,
    "fileType": null
  },
  "4fb96f75-6828-5673-c4gd-3d074g77bgb7": {
    "value": "John Doe",
    "fileUrl": null,
    "fileName": null,
    "fileSize": null,
    "fileType": null
  },
  "5gc07g86-7939-6784-d5he-4e185h88chc8": {
    "value": null,
    "fileUrl": "https://storage.example.com/resumes/john-doe-resume.pdf",
    "fileName": "john-doe-resume.pdf",
    "fileSize": 125000,
    "fileType": "application/pdf"
  }
}

Request Body Structure: The request body is a map where:

Key: Field UUID (string)
Value: AnswerValue object containing:

Field	Type	Required	Description	Used For
value	any	Conditional	The answer value	All non-file fields (text, number, date, selections, etc.)
fileUrl	string	Conditional	URL of uploaded file	FILE type fields only
fileName	string	Conditional	Original filename	FILE type fields only
fileSize	long	Conditional	File size in bytes	FILE type fields only
fileType	string	Conditional	MIME type	FILE type fields only

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Page saved",
  "action_time": "2026-02-03T11:45:50",
  "data": {
    "responseId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "formId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "submittedBy": "john.doe@example.com",
    "status": "DRAFT",
    "completedPageIds": ["9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"],
    "currentPageIndex": 1,
    "startedAt": "2026-02-03T11:35:15Z",
    "submittedAt": null,
    "completionTimeSeconds": null,
    "answers": [
      {
        "answerId": "ans-001",
        "fieldId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "fieldLabel": "Email Address",
        "fieldType": "EMAIL",
        "fieldDeleted": false,
        "value": "john.doe@example.com",
        "answeredAt": "2026-02-03T11:45:50Z",
        "fileUrl": null,
        "fileName": null,
        "fileSize": null,
        "fileType": null
      },
      {
        "answerId": "ans-002",
        "fieldId": "4fb96f75-6828-5673-c4gd-3d074g77bgb7",
        "fieldLabel": "Full Name",
        "fieldType": "TEXT",
        "fieldDeleted": false,
        "value": "John Doe",
        "answeredAt": "2026-02-03T11:45:50Z",
        "fileUrl": null,
        "fileName": null,
        "fileSize": null,
        "fileType": null
      },
      {
        "answerId": "ans-003",
        "fieldId": "5gc07g86-7939-6784-d5he-4e185h88chc8",
        "fieldLabel": "Resume",
        "fieldType": "FILE",
        "fieldDeleted": false,
        "value": null,
        "answeredAt": "2026-02-03T11:45:50Z",
        "fileUrl": "https://storage.example.com/resumes/john-doe-resume.pdf",
        "fileName": "john-doe-resume.pdf",
        "fileSize": 125000,
        "fileType": "application/pdf"
      }
    ]
  }
}

Error Response Examples:

Validation Error (422):

{
  "success": false,
  "httpStatus": "UNPROCESSABLE_ENTITY",
  "message": "Validation failed",
  "action_time": "2026-02-03T11:45:50",
  "data": {
    "fieldErrors": [
      {
        "pageId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
        "pageTitle": "Personal Information",
        "fieldId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "fieldLabel": "Email Address",
        "errorMessage": "must be a well-formed email address",
        "errorType": "INVALID_FORMAT"
      }
    ]
  }
}

Start Submission First (404):

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Start submission first",
  "action_time": "2026-02-03T11:45:50",
  "data": "Start submission first"
}

16. Submit Form

Purpose: Finalizes the form submission, validates all required fields, and marks response as complete.

Endpoint: POST /events/{eventId}/submit

Access Level: 🔒 Protected (Authenticated Attendee)

Authentication: Bearer Token Required

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Path Parameters:

Parameter	Type	Required	Description	Validation
eventId	UUID	Yes	Unique identifier of the event	Valid UUID format

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Form submitted successfully",
  "action_time": "2026-02-03T11:50:30",
  "data": {
    "responseId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "formId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "submittedBy": "john.doe@example.com",
    "status": "SUBMITTED",
    "completedPageIds": [
      "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "8a0cda3c-2a6c-3a9c-8acc-1a9c6a2dca5c"
    ],
    "currentPageIndex": 2,
    "startedAt": "2026-02-03T11:35:15Z",
    "submittedAt": "2026-02-03T11:50:30Z",
    "completionTimeSeconds": 915,
    "answers": [
      {
        "answerId": "ans-001",
        "fieldId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "fieldLabel": "Email Address",
        "fieldType": "EMAIL",
        "fieldDeleted": false,
        "value": "john.doe@example.com",
        "answeredAt": "2026-02-03T11:45:50Z",
        "fileUrl": null,
        "fileName": null,
        "fileSize": null,
        "fileType": null
      }
    ]
  }
}

Success Response Fields:

Field	Description
status	Now "SUBMITTED" instead of "DRAFT"
submittedAt	Timestamp when form was finalized
completionTimeSeconds	Total time taken from start to submit

Error Response Examples:

Incomplete Form (422):

{
  "success": false,
  "httpStatus": "UNPROCESSABLE_ENTITY",
  "message": "Validation failed",
  "action_time": "2026-02-03T11:50:30",
  "data": {
    "fieldErrors": [
      {
        "pageId": "8a0cda3c-2a6c-3a9c-8acc-1a9c6a2dca5c",
        "pageTitle": "Contact Details",
        "fieldId": "7hd18i97-8a4a-7895-e6if-5f296i99did9",
        "fieldLabel": "Phone Number",
        "errorMessage": "This field is required",
        "errorType": "REQUIRED_FIELD"
      }
    ]
  }
}

Already Submitted (403):

{
  "success": false,
  "httpStatus": "FORBIDDEN",
  "message": "Already submitted",
  "action_time": "2026-02-03T11:50:30",
  "data": "Already submitted"
}

17. Get Response by ID

Purpose: Allows organizer to view a specific attendee's form response with all answers.

Endpoint: GET /events/{eventId}/responses/{responseId}

Access Level: 🔒 Protected (Event Organizer Only)

Authentication: Bearer Token Required

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Path Parameters:

Parameter	Type	Required	Description	Validation
eventId	UUID	Yes	Unique identifier of the event	Valid UUID format
responseId	UUID	Yes	Unique identifier of the response	Valid UUID format

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Response retrieved",
  "action_time": "2026-02-03T12:00:15",
  "data": {
    "responseId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "formId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "submittedBy": "john.doe@example.com",
    "status": "SUBMITTED",
    "completedPageIds": [
      "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "8a0cda3c-2a6c-3a9c-8acc-1a9c6a2dca5c"
    ],
    "currentPageIndex": 2,
    "startedAt": "2026-02-03T11:35:15Z",
    "submittedAt": "2026-02-03T11:50:30Z",
    "completionTimeSeconds": 915,
    "answers": [
      {
        "answerId": "ans-001",
        "fieldId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "fieldLabel": "Email Address",
        "fieldType": "EMAIL",
        "fieldDeleted": false,
        "value": "john.doe@example.com",
        "answeredAt": "2026-02-03T11:45:50Z",
        "fileUrl": null,
        "fileName": null,
        "fileSize": null,
        "fileType": null
      },
      {
        "answerId": "ans-002",
        "fieldId": "4fb96f75-6828-5673-c4gd-3d074g77bgb7",
        "fieldLabel": "Full Name",
        "fieldType": "TEXT",
        "fieldDeleted": false,
        "value": "John Doe",
        "answeredAt": "2026-02-03T11:45:50Z",
        "fileUrl": null,
        "fileName": null,
        "fileSize": null,
        "fileType": null
      }
    ]
  }
}

18. Get All Responses

Purpose: Retrieves paginated list of all form responses for the event (organizer view).

Endpoint: GET /events/{eventId}/responses

Access Level: 🔒 Protected (Event Organizer Only)

Authentication: Bearer Token Required

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Path Parameters:

Parameter	Type	Required	Description	Validation
eventId	UUID	Yes	Unique identifier of the event	Valid UUID format

Query Parameters:

Parameter	Type	Required	Description	Validation	Default
page	integer	No	Page number (zero-based)	Min: 0	0
size	integer	No	Items per page	Min: 1, Max: 100	20

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Responses retrieved",
  "action_time": "2026-02-03T12:05:45",
  "data": {
    "content": [
      {
        "responseId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "formId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "submittedBy": "john.doe@example.com",
        "status": "SUBMITTED",
        "startedAt": "2026-02-03T11:35:15Z",
        "submittedAt": "2026-02-03T11:50:30Z",
        "completionTimeSeconds": 915
      },
      {
        "responseId": "b2c3d4e5-f6g7-8901-bcde-fg2345678901",
        "formId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "submittedBy": "jane.smith@example.com",
        "status": "DRAFT",
        "startedAt": "2026-02-03T12:00:00Z",
        "submittedAt": null,
        "completionTimeSeconds": null
      }
    ],
    "pageable": {
      "pageNumber": 0,
      "pageSize": 20,
      "sort": {
        "sorted": false,
        "unsorted": true,
        "empty": true
      },
      "offset": 0,
      "paged": true,
      "unpaged": false
    },
    "totalPages": 1,
    "totalElements": 2,
    "last": true,
    "first": true,
    "size": 20,
    "number": 0,
    "numberOfElements": 2,
    "empty": false
  }
}

Success Response Fields:

Field	Description
content	Array of response objects
pageable	Pagination metadata
totalPages	Total number of pages
totalElements	Total number of responses
last	Whether this is the last page
first	Whether this is the first page
size	Page size
number	Current page number
numberOfElements	Number of items in current page
empty	Whether the result is empty

19. Get Form Analytics

Purpose: Retrieves comprehensive analytics for the form including submission stats, field-level analytics, and trends.

Endpoint: GET /events/{eventId}/analytics

Access Level: 🔒 Protected (Event Organizer Only)

Authentication: Bearer Token Required

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Path Parameters:

Parameter	Type	Required	Description	Validation
eventId	UUID	Yes	Unique identifier of the event	Valid UUID format

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Analytics retrieved",
  "action_time": "2026-02-03T12:10:30",
  "data": {
    "formId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "formTitle": "Attendee Questions - Tech Conference 2026",
    "stats": {
      "totalStarted": 150,
      "totalDrafts": 23,
      "totalSubmitted": 125,
      "totalWithdrawn": 2,
      "completionRate": 83.33,
      "dropOffRate": 16.67,
      "avgCompletionTimeSeconds": 780.5,
      "fastestTimeSeconds": 245,
      "slowestTimeSeconds": 1850
    },
    "fieldAnalytics": [
      {
        "fieldId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "fieldLabel": "Email Address",
        "fieldType": "EMAIL",
        "fieldDeleted": false,
        "totalResponses": 125,
        "uniqueResponses": 125,
        "choiceDistribution": null,
        "numericStats": null,
        "textResponses": null
      },
      {
        "fieldId": "6ie29j08-9b5b-8a06-f7jg-6g307j00eje0",
        "fieldLabel": "Job Role",
        "fieldType": "DROPDOWN",
        "fieldDeleted": false,
        "totalResponses": 125,
        "uniqueResponses": 8,
        "choiceDistribution": [
          {
            "option": "Software Developer",
            "count": 45,
            "percentage": 36.0
          },
          {
            "option": "Product Manager",
            "count": 30,
            "percentage": 24.0
          },
          {
            "option": "Designer",
            "count": 25,
            "percentage": 20.0
          },
          {
            "option": "Other",
            "count": 25,
            "percentage": 20.0
          }
        ],
        "numericStats": null,
        "textResponses": null
      },
      {
        "fieldId": "7jf30k19-0c6c-9b17-g8kh-7h418k11fkf1",
        "fieldLabel": "Years of Experience",
        "fieldType": "NUMBER",
        "fieldDeleted": false,
        "totalResponses": 125,
        "uniqueResponses": 25,
        "choiceDistribution": null,
        "numericStats": {
          "min": 0.0,
          "max": 25.0,
          "avg": 5.8,
          "median": 4.0
        },
        "textResponses": null
      }
    ],
    "dailySubmissions": [
      {
        "date": "2026-02-01",
        "count": 45
      },
      {
        "date": "2026-02-02",
        "count": 52
      },
      {
        "date": "2026-02-03",
        "count": 28
      }
    ]
  }
}

Success Response Fields:

stats object:

Field	Description
totalStarted	Total number of attendees who started the form
totalDrafts	Number of incomplete submissions
totalSubmitted	Number of completed submissions
totalWithdrawn	Number of withdrawn submissions
completionRate	Percentage of started forms that were submitted
dropOffRate	Percentage of started forms not submitted
avgCompletionTimeSeconds	Average time to complete form
fastestTimeSeconds	Fastest completion time
slowestTimeSeconds	Slowest completion time

fieldAnalytics array objects:

Field	Description
fieldId	Unique identifier of the field
fieldLabel	Field label (snapshot at time of response)
fieldType	Type of field
fieldDeleted	Whether field has been deleted
totalResponses	Total number of responses for this field
uniqueResponses	Number of unique values
choiceDistribution	For choice fields: breakdown of selections
numericStats	For numeric fields: min, max, avg, median
textResponses	For text fields: array of responses (if applicable)

dailySubmissions array objects:

Field	Description
date	Date in YYYY-MM-DD format
count	Number of submissions on that date

Standard Error Types

Application-Level Exceptions (400-499)

400 BAD_REQUEST: Invalid request data or item already exists
401 UNAUTHORIZED: Authentication issues (missing, invalid, or expired tokens)
403 FORBIDDEN: Access denied, permission issues, verification failures
404 NOT_FOUND: Requested resource does not exist
422 UNPROCESSABLE_ENTITY: Validation errors with detailed field information
429 TOO_MANY_REQUESTS: Rate limit exceeded

Server-Level Exceptions (500+)

500 INTERNAL_SERVER_ERROR: Unexpected server errors

Common HTTP Status Codes

200 OK: Successful GET/PUT request
201 Created: Successful POST request
204 No Content: Successful DELETE request (not used in this API - we return 200 with message)
400 Bad Request: Invalid request data
401 Unauthorized: Authentication required/failed
403 Forbidden: Insufficient permissions
404 Not Found: Resource not found
422 Unprocessable Entity: Validation errors
500 Internal Server Error: Server error

Field Type Reference

Field Type	Description	Validation Options	Answer Format
TEXT	Single-line text input	min, max, pattern	String value
TEXTAREA	Multi-line text input	min, max	String value
EMAIL	Email address input	Email format validation	String value
PHONE	Phone number input	Phone format validation	String value
NUMBER	Numeric input	min, max	Number value
DATE	Date picker	Date format	ISO 8601 date string
DROPDOWN	Single-choice dropdown	Requires options	Option label (string)
RADIO	Single-choice radio buttons	Requires options	Option label (string)
CHECKBOX	Multiple-choice checkboxes	Requires options	Array of option labels
FILE	File upload	allowedFileTypes, maxFileSize	File metadata object
URL	URL input	URL format validation	String value
CURRENCY	Currency amount	min, max	Number value (in cents)
RATING	Star/numeric rating	min, max	Number value
SCALE	Linear scale (1-5, 1-10, etc.)	min, max	Number value
SLIDER	Slider input	min, max	Number value
SECTION_HEADER	Display-only section title	None (display only)	No answer
PARAGRAPH	Display-only paragraph text	None (display only)	No answer

Integration with Ticket Checkout

When displayTime is set to BEFORE_CHECKOUT and isRequiredOnline is true, the checkout flow enforces form completion:

Attendee attempts to purchase ticket
System checks if form is required before checkout
If form not submitted, checkout is blocked with error:

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Please complete the event questionnaire before purchasing tickets",
  "action_time": "2026-02-03T12:15:00",
  "data": "Please complete the event questionnaire before purchasing tickets"
}

Attendee completes and submits form
Attendee can now proceed to checkout

When displayTime is set to AFTER_CHECKOUT, the form link is sent to attendees after successful ticket purchase via email or notification.

Quick Reference - Endpoint Summary

#	Method	Endpoint	Purpose	Access
1	POST	`/events/{eventId}/enable`	Enable form	Organizer
2	PUT	`/events/{eventId}/settings`	Update settings	Organizer
3	DELETE	`/events/{eventId}/disable`	Disable form	Organizer
4	POST	`/events/{eventId}/pages`	Add page	Organizer
5	PUT	`/events/{eventId}/pages/{pageId}`	Update page	Organizer
6	DELETE	`/events/{eventId}/pages/{pageId}`	Delete page	Organizer
7	POST	`/events/{eventId}/pages/{pageId}/fields`	Add field	Organizer
8	PUT	`/events/{eventId}/fields/{fieldId}`	Update field	Organizer
9	DELETE	`/events/{eventId}/fields/{fieldId}`	Delete field	Organizer
10	POST	`/events/{eventId}/fields/{fieldId}/options`	Add option	Organizer
11	PUT	`/events/{eventId}/options/{optionId}`	Update option	Organizer
12	DELETE	`/events/{eventId}/options/{optionId}`	Delete option	Organizer
13	POST	`/events/{eventId}/start`	Start submission	Attendee
14	GET	`/events/{eventId}/my-response`	View my response	Attendee
15	PUT	`/events/{eventId}/pages/{pageId}/save`	Save page	Attendee
16	POST	`/events/{eventId}/submit`	Submit form	Attendee
17	GET	`/events/{eventId}/responses/{responseId}`	View response	Organizer
18	GET	`/events/{eventId}/responses`	List responses	Organizer
19	GET	`/events/{eventId}/analytics`	View analytics	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

Event Applicant Form API

Attendee Questions API Guide

Event Applicant Form API

Event Registration Flow Diagram

Standard Response Format

Success Response Structure

Error Response Structure

Standard Response Fields

HTTP Method Badge Standards

Endpoints

1. Enable Applicant Form

2. Update Form Settings

3. Disable Applicant Form

4. Add Page to Form

5. Update Page

6. Delete Page

7. Add Field to Page

8. Update Field

9. Delete Field

10. Add Option to Field

11. Update Option

12. Delete Option

13. Start Form Submission

14. Get My Response

15. Save Page Answers

16. Submit Form

17. Get Response by ID

18. Get All Responses

19. Get Form Analytics

Standard Error Types

Application-Level Exceptions (400-499)

Server-Level Exceptions (500+)

Common HTTP Status Codes

Field Type Reference

Integration with Ticket Checkout

Quick Reference - Endpoint Summary