Proposals

Overview

The Proposals API allows organizers to submit event proposals for approval, view their proposals, and resubmit rejected proposals with modifications.

All proposal endpoints require authentication with the ORGANIZER role.

List My Proposals

curl -X GET https://api.example.com/api/proposals \
  -H "Authorization: Bearer YOUR_TOKEN"

GET /api/proposals
Authorization: Bearer YOUR_TOKEN

Retrieve all proposals submitted by the authenticated organizer.

Authentication

Required Role: ORGANIZER (enforced by @PreAuthorize("hasRole('ORGANIZER')"))

Response

statusCode

integer

HTTP status code (200)

message

string

Success message: “Proposals fetched successfully”

data

array

Array of proposal objects

data[].proposalID

integer

Unique proposal identifier

data[].title

string

Proposal title

data[].description

string

Detailed description of the proposed event

data[].proposedDate

string

Proposed event date (YYYY-MM-DD)

data[].startTime

string

Proposed start time (HH:mm:ss)

data[].endTime

string

Proposed end time (HH:mm:ss)

data[].venue

string

Proposed venue/location

data[].capacity

integer

Maximum participant capacity

data[].organizationType

string

Organization type: YOUTH_UNION, STUDENT_ASSOCIATION, FACULTY, UNIVERSITY

data[].status

string

Proposal status: PENDING_L1, PENDING_L2, PENDING_L3, APPROVED, REJECTED

data[].attachmentsJson

string

JSON string containing attachment metadata

data[].submittedAt

string

ISO 8601 timestamp when proposal was submitted

data[].reviewedAt

string

ISO 8601 timestamp when proposal was reviewed (null if pending)

data[].reviewedByID

integer

ID of admin who reviewed the proposal

data[].rejectionReason

string

Reason for rejection (null if approved or pending)

data[].organizerID

integer

ID of the organizer who submitted the proposal

data[].organizerName

string

Full name of the organizer

{
  "statusCode": 200,
  "message": "Proposals fetched successfully",
  "data": [
    {
      "proposalID": 1,
      "title": "Spring Tech Conference 2024",
      "description": "A comprehensive tech conference featuring industry leaders",
      "proposedDate": "2024-05-15",
      "startTime": "09:00:00",
      "endTime": "17:00:00",
      "venue": "Main Auditorium",
      "capacity": 300,
      "organizationType": "FACULTY",
      "status": "APPROVED",
      "attachmentsJson": "[{\"name\":\"budget.pdf\",\"url\":\"https://...\"}]",
      "submittedAt": "2024-03-01T10:00:00",
      "reviewedAt": "2024-03-03T14:30:00",
      "reviewedByID": 10,
      "rejectionReason": null,
      "organizerID": 5,
      "organizerName": "Jane Smith"
    },
    {
      "proposalID": 2,
      "title": "Student Networking Event",
      "description": "Networking opportunity for students and alumni",
      "proposedDate": "2024-04-20",
      "startTime": "18:00:00",
      "endTime": "21:00:00",
      "venue": "Student Center",
      "capacity": 150,
      "organizationType": "STUDENT_ASSOCIATION",
      "status": "PENDING_L1",
      "attachmentsJson": null,
      "submittedAt": "2024-03-05T09:00:00",
      "reviewedAt": null,
      "reviewedByID": null,
      "rejectionReason": null,
      "organizerID": 5,
      "organizerName": "Jane Smith"
    }
  ],
  "timestamp": "2024-03-07T10:30:00"
}

Create Proposal

curl -X POST https://api.example.com/api/proposals \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F 'proposal={
    "title": "Spring Tech Conference",
    "description": "A tech conference",
    "proposedDate": "2024-05-15",
    "startTime": "09:00:00",
    "endTime": "17:00:00",
    "venue": "Main Auditorium",
    "capacity": 300,
    "organizationType": "FACULTY"
  }' \
  -F '[email protected]' \
  -F '[email protected]'

POST /api/proposals
Content-Type: multipart/form-data
Authorization: Bearer YOUR_TOKEN

Submit a new event proposal for administrative approval. This endpoint uses multipart/form-data to support file uploads.

Authentication

Required Role: ORGANIZER (enforced by @PreAuthorize("hasRole('ORGANIZER')"))

Request Parts

proposal

string

required

JSON string containing the proposal data (see fields below)

files

file[]

Optional array of files to attach (PDF, images, etc.)

Proposal JSON Fields

title

string

required

Event title (validated: not blank)

description

string

Detailed event description

proposedDate

string

required

Proposed event date in YYYY-MM-DD format (must be in the future)

startTime

string

required

Start time in HH:mm:ss format

endTime

string

required

End time in HH:mm:ss format

venue

string

required

Event venue/location (validated: not blank)

capacity

integer

required

Maximum participant capacity (minimum: 1)

organizationType

enum

required

Organization type: YOUTH_UNION, STUDENT_ASSOCIATION, FACULTY, or UNIVERSITY

Response

{
  "statusCode": 201,
  "message": "Proposal submitted successfully and is pending approval",
  "data": {
    "proposalID": 3,
    "title": "Spring Tech Conference",
    "description": "A tech conference",
    "proposedDate": "2024-05-15",
    "startTime": "09:00:00",
    "endTime": "17:00:00",
    "venue": "Main Auditorium",
    "capacity": 300,
    "organizationType": "FACULTY",
    "status": "PENDING_L1",
    "attachmentsJson": "[{\"name\":\"budget.pdf\",\"size\":102400,\"url\":\"https://...\"}]",
    "submittedAt": "2024-03-07T10:30:00",
    "reviewedAt": null,
    "reviewedByID": null,
    "rejectionReason": null,
    "organizerID": 5,
    "organizerName": "Jane Smith"
  },
  "timestamp": "2024-03-07T10:30:00"
}

Error Responses

{
  "statusCode": 400,
  "message": "Validation failed",
  "errors": [
    "Title is required",
    "Proposed date must be in the future",
    "Capacity must be at least 1"
  ],
  "timestamp": "2024-03-07T10:30:00"
}

Resubmit Proposal

curl -X PUT https://api.example.com/api/proposals/2/resubmit \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F 'proposal={
    "title": "Updated Spring Tech Conference",
    "description": "Updated description",
    "proposedDate": "2024-06-01",
    "startTime": "10:00:00",
    "endTime": "18:00:00",
    "venue": "New Auditorium",
    "capacity": 350,
    "organizationType": "FACULTY"
  }' \
  -F 'files=@updated_budget.pdf'

PUT /api/proposals/{proposalID}/resubmit
Content-Type: multipart/form-data
Authorization: Bearer YOUR_TOKEN

Update and resubmit a rejected proposal. This resets the approval status to PENDING_L1.

Authentication

Required Role: ORGANIZER (enforced by @PreAuthorize("hasRole('ORGANIZER')"))

Path Parameters

proposalID

integer

required

ID of the proposal to resubmit

Request Parts

Same as the create endpoint:

proposal - JSON string with updated proposal data
files - Optional new file attachments

Response

{
  "statusCode": 200,
  "message": "Proposal resubmitted successfully",
  "data": {
    "proposalID": 2,
    "title": "Updated Spring Tech Conference",
    "description": "Updated description",
    "proposedDate": "2024-06-01",
    "startTime": "10:00:00",
    "endTime": "18:00:00",
    "venue": "New Auditorium",
    "capacity": 350,
    "organizationType": "FACULTY",
    "status": "PENDING_L1",
    "attachmentsJson": "[{\"name\":\"updated_budget.pdf\",\"size\":156000,\"url\":\"https://...\"}]",
    "submittedAt": "2024-03-07T11:00:00",
    "reviewedAt": null,
    "reviewedByID": null,
    "rejectionReason": null,
    "organizerID": 5,
    "organizerName": "Jane Smith"
  },
  "timestamp": "2024-03-07T11:00:00"
}

Error Responses

{
  "statusCode": 403,
  "message": "You can only resubmit your own proposals",
  "timestamp": "2024-03-07T10:30:00"
}

Proposal Status Flow

Proposals go through a multi-level approval process:

PENDING_L1 - Initial submission, awaiting first-level admin review (Youth Union/Student Association)
PENDING_L2 - Awaiting faculty-level review
PENDING_L3 - Awaiting rector-level review (for high-level events)
APPROVED - Proposal approved and converted to an event
REJECTED - Proposal rejected (can be resubmitted)

The approval flow depends on the organizationType of the proposal.

Overview

Endpoints

Overview

List My Proposals

Authentication

Response

Create Proposal

Authentication

Request Parts

Proposal JSON Fields

Response

Error Responses

Resubmit Proposal

Authentication

Path Parameters

Request Parts

Response

Error Responses

Proposal Status Flow

Build docs developers (and LLMs) love

Overview

Endpoints

​Overview

​List My Proposals

​Authentication

​Response

​Create Proposal

​Authentication

​Request Parts

​Proposal JSON Fields

​Response

​Error Responses

​Resubmit Proposal

​Authentication

​Path Parameters

​Request Parts

​Response

​Error Responses

​Proposal Status Flow

Build docs developers (and LLMs) love

Overview

List My Proposals

Authentication

Response

Create Proposal

Authentication

Request Parts

Proposal JSON Fields

Response

Error Responses

Resubmit Proposal

Authentication

Path Parameters

Request Parts

Response

Error Responses

Proposal Status Flow