Manage event participation

Use event operations to read a workspace’s events, keep a participant list in step with another system, and record attendance after the event. The API applies the same rules as the Floral app: capacity, waitlists, registration windows, and attendance finalisation behave identically.

Prerequisites

The workspace has the Events add-on, and your token’s owner can use Work in that workspace.
The token has events:read to read events and participants, and events:write to change them. Each scope grants only its own access; a write token cannot read.
You can only see events that the token’s owner can see in Floral. An event or participant you cannot see returns 404 NOT_FOUND, exactly as if it did not exist.

If the Events add-on is not available to the workspace, every event operation returns 404 FEATURE_DISABLED. Set these values once in your shell before running the examples:

export FLORAL_BASE_URL="https://app.floral.so/api/v1"
export FLORAL_WORKSPACE="your-workspace"
export FLORAL_TOKEN="floral_pat_..."

Use a personal access token created for this workspace. The examples use synthetic IDs and values; replace them with values returned by your workspace.

Keep FLORAL_TOKEN in a secret manager outside local development. Never commit it to source control or include it in logs.

List and filter events

Event collections use opaque cursor pagination with at most 50 items per page. Filter by planning status, attendance finalisation, owner, or a local date range.

curl --get --fail-with-body \
  --url "$FLORAL_BASE_URL/workspaces/$FLORAL_WORKSPACE/events" \
  --header "Authorization: Bearer $FLORAL_TOKEN" \
  --data-urlencode "planningStatus=READY" \
  --data-urlencode "from=2026-09-01" \
  --data-urlencode "to=2026-09-30" \
  --data-urlencode "sort=starts-asc" \
  --data-urlencode "limit=20"

Pass a non-null nextCursor as cursor with the same filters and sort to get the next page.

Retrieve an event and its version

curl --request GET --fail-with-body --include \
  --url "$FLORAL_BASE_URL/workspaces/$FLORAL_WORKSPACE/events/42" \
  --header "Authorization: Bearer $FLORAL_TOKEN"

The strong ETag header and the version field carry the event’s current version. You need it to finalise attendance.

List participants

Participants are returned in registration order. Filter by registration state, attendance state, or CRM match status.

curl --get --fail-with-body \
  --url "$FLORAL_BASE_URL/workspaces/$FLORAL_WORKSPACE/events/42/participants" \
  --header "Authorization: Bearer $FLORAL_TOKEN" \
  --data-urlencode "registrationState=REGISTERED" \
  --data-urlencode "limit=50"

Each participant has a UUID id and its own version. The responses object holds ordinary registration answers only.

Read restricted answers

Answers to fields marked as restricted, such as dietary or accessibility needs, are never part of the participant resource. Only the event organiser or a workspace admin can read them, from a separate operation:

curl --request GET --fail-with-body \
  --url "$FLORAL_BASE_URL/workspaces/$FLORAL_WORKSPACE/events/42/participants/0f8b6c1e-3a52-4d6e-9b7a-2c4e5f6a7b8c/restricted-responses" \
  --header "Authorization: Bearer $FLORAL_TOKEN"

Anyone else receives 403 FORBIDDEN. Store these answers only as long as you need them for the event’s logistics.

Register a participant

Registration requires an Idempotency-Key. Answers are validated against the event’s registration form.

export REGISTRATION_KEY="01J5C7A2B9M4K8T1Q6D3R0V5XZ"

curl --request POST --fail-with-body --include \
  --url "$FLORAL_BASE_URL/workspaces/$FLORAL_WORKSPACE/events/42/participants" \
  --header "Authorization: Bearer $FLORAL_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $REGISTRATION_KEY" \
  --data '{
    "name": "Ada Jensen",
    "email": "ada@example.com",
    "companyName": "Acme Nordic",
    "responses": { "session_track": "Operations" }
  }'

A successful registration returns 201 with a Location header and the participant’s ETag. When the event is full and has a waitlist, the participant is created with WAITLISTED state and a waitlistPosition. When registration is closed, or the event is full without a waitlist, the operation returns 409 CONFLICT and creates nothing.

Update a participant

Send only the fields you want to change, with the participant’s latest ETag. Sending null clears an optional field.

export PARTICIPANT_ETAG='"v1.ZXhhbXBsZS1wYXJ0aWNpcGFudA"'

curl --request PATCH --fail-with-body --include \
  --url "$FLORAL_BASE_URL/workspaces/$FLORAL_WORKSPACE/events/42/participants/0f8b6c1e-3a52-4d6e-9b7a-2c4e5f6a7b8c" \
  --header "Authorization: Bearer $FLORAL_TOKEN" \
  --header "Content-Type: application/json" \
  --header "If-Match: $PARTICIPANT_ETAG" \
  --data '{"phone": "+45 12 34 56 78"}'

Only the event organiser or a workspace admin can change answers to restricted fields. A request from anyone else that includes a restricted field returns 403 FORBIDDEN and changes nothing.

Mark attendance

Mark up to 500 registered participants in one request. Marking requires an Idempotency-Key but no If-Match, so several people can check guests in at the same time.

export CHECK_IN_KEY="01J5C7F4H2N6P9R3S8T1V5W0YA"

curl --request POST --fail-with-body \
  --url "$FLORAL_BASE_URL/workspaces/$FLORAL_WORKSPACE/events/42/attendance" \
  --header "Authorization: Bearer $FLORAL_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $CHECK_IN_KEY" \
  --data '{
    "participantIds": ["0f8b6c1e-3a52-4d6e-9b7a-2c4e5f6a7b8c"],
    "state": "ATTENDED"
  }'

A batch is applied completely or not at all. It fails with 404 NOT_FOUND if any ID does not belong to the event, with 409 INVALID_STATE if any participant is not registered, and with 409 INVALID_STATE after attendance has been finalised. The response lists the participants whose state changed and those that already had it.

Finalise attendance

Finalising locks attendance for follow-up. It requires the event’s latest ETag and an Idempotency-Key. List the registered participants who did not attend; everyone else who is still unmarked stays UNKNOWN.

export EVENT_ETAG='"v1.ZXhhbXBsZS1ldmVudA"'
export FINALISE_KEY="01J5C7K8M1P4R7T0V3X6Z9B2DC"

curl --request POST --fail-with-body --include \
  --url "$FLORAL_BASE_URL/workspaces/$FLORAL_WORKSPACE/events/42/attendance/finalise" \
  --header "Authorization: Bearer $FLORAL_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $FINALISE_KEY" \
  --header "If-Match: $EVENT_ETAG" \
  --data '{"noShowParticipantIds": []}'

Finalising an event that is already finalised returns 409 INVALID_STATE.

Correct finalised attendance

After finalisation, correct one participant at a time with a reason. Send the participant’s latest ETag.

export CORRECTION_KEY="01J5C7Q2S5U8W1Y4A7C0E3G6HJ"

curl --request POST --fail-with-body --include \
  --url "$FLORAL_BASE_URL/workspaces/$FLORAL_WORKSPACE/events/42/participants/0f8b6c1e-3a52-4d6e-9b7a-2c4e5f6a7b8c/attendance-correction" \
  --header "Authorization: Bearer $FLORAL_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $CORRECTION_KEY" \
  --header "If-Match: $PARTICIPANT_ETAG" \
  --data '{"state": "ATTENDED", "reason": "Signed in at the side entrance."}'

Floral keeps the earlier attendance record and marks it as superseded, so the correction history stays auditable. Floral protects writes with two opaque values:

Send a unique Idempotency-Key when an operation requires one. Retrying the identical request with the same key replays its result for 24 hours. Within that operation, reusing the key with different canonical input returns 409 IDEMPOTENCY_CONFLICT.
Send the latest strong ETag as If-Match when an operation changes an existing resource. A stale value returns 412 VERSION_CONFLICT; a missing value returns 428 PRECONDITION_REQUIRED.

Keep the quote characters around an ETag, and replace your saved value after every successful write. See Reliability and retries for the complete retry rules.

Start here

MCP

Public API

API guides

Manage event participation

Prerequisites

List and filter events

Retrieve an event and its version

List participants

Read restricted answers

Register a participant

Update a participant

Mark attendance

Finalise attendance

Correct finalised attendance

​Prerequisites

​List and filter events

​Retrieve an event and its version

​List participants

​Read restricted answers

​Register a participant

​Update a participant

​Mark attendance

​Finalise attendance

​Correct finalised attendance

Prerequisites

List and filter events

Retrieve an event and its version

List participants

Read restricted answers

Register a participant

Update a participant

Mark attendance

Finalise attendance

Correct finalised attendance