Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ptshen/timeful-plus/llms.txt

Use this file to discover all available pages before exploring further.

Sign-up forms flip the scheduling interaction: instead of everyone marking their availability and waiting for the organizer to pick a time, participants claim a specific slot that the organizer has pre-defined. First come, first served. Once a slot is full, it’s gone. This makes sign-up forms the right tool whenever the organizer controls the schedule and participants need to self-assign — rather than the other way around.

​
Sign-Up Forms vs. Availability Polls

Availability PollSign-Up Form
Who controls the times?Organizer picks dates; participants voteOrganizer defines exact time blocks
What participants doMark when they’re freeClaim a specific slot
ResultOrganizer sees overlap, then picks a timeEach slot is reserved immediately
CapacityOptional maxCapacityPerSlot limitPer-block capacity field
Best forFinding a consensus meeting timeOffice hours, lab slots, advisor sign-ups

​
Enabling Sign-Up Mode

Sign-up forms are built on the same Event model as availability polls. Setting isSignUpForm: true switches the event into sign-up mode: 
// From server/models/event.go
IsSignUpForm  *bool                      `json:"isSignUpForm" bson:"isSignUpForm,omitempty"`
SignUpMode    *string                    `json:"signUpMode" bson:"signUpMode,omitempty"`
SignUpBlocks  *[]SignUpBlock             `json:"signUpBlocks" bson:"signUpBlocks,omitempty"`
SignUpResponses map[string]*SignUpResponse `json:"signUpResponses" bson:"signUpResponses"`

​
Sign-Up Modes

The signUpMode field selects between two interaction models, defined as constants in frontend/src/constants.js: 
export const signUpModes = Object.freeze({
  TIME_SLOTS: "time_slots",
  PROJECTS:   "projects",
})
Participants claim one or more time-based blocks (e.g., 2:00 PM – 2:30 PM on Tuesday). Each block has a defined start time, end time, and capacity. This is the default mode and the one most useful for office hours and advisor appointments.

​
The SignUpBlock Model

Each time slot or project slot is represented as a SignUpBlock document, embedded in the Event: 
// From server/models/event.go
type SignUpBlock struct {
    Id        primitive.ObjectID  `json:"_id" bson:"_id,omitempty"`
    Name      string              `json:"name" bson:"name,omitempty"`
    Capacity  *int                `json:"capacity" bson:"capacity,omitempty"`
    StartDate *primitive.DateTime `json:"startDate" bson:"startDate,omitempty"`
    EndDate   *primitive.DateTime `json:"endDate" bson:"endDate,omitempty"`
}
FieldDescription
IdUnique ObjectID for the block. Auto-generated by ensureSignUpBlockIDs() if omitted at creation time.
NameDisplay label for the block (e.g., "Office Hours – Slot 3" or "Project: Algebraic Topology").
CapacityMaximum number of participants who can claim this block. nil means unlimited.
StartDateStart timestamp of the block (used in time_slots mode).
EndDateEnd timestamp of the block (used in time_slots mode).
SignUpBlock.Capacity is distinct from Event.MaxCapacityPerSlot. SignUpBlock.Capacity limits how many people can claim a particular named block in a sign-up form. MaxCapacityPerSlot is the Columbia Math Department addition that limits availability per grid cell in a regular poll.

​
Sign-Up Responses

When a participant claims a block, their selection is stored as a SignUpResponse in the SignUpResponses map on the Event document, keyed by user ID or guest name: 
// From server/models/event.go
type SignUpResponse struct {
    // The IDs of the sign up blocks the user has claimed
    SignUpBlockIds []primitive.ObjectID `json:"signUpBlockIds" bson:"signUpBlockIds,omitempty"`

    // Guest information (when not signed in)
    Name  string `json:"name" bson:"name,omitempty"`
    Email string `json:"email" bson:"email,omitempty"`

    // Authenticated user information
    UserId primitive.ObjectID `json:"userId" bson:"userId,omitempty"`
    User   *User              `json:"user" bson:",omitempty"`
}

​
Guest Sign-Ups

Participants who are not signed in can still claim slots by providing their name and email in the response. The Name and Email fields on SignUpResponse are populated for guest users. This is useful when the sign-up form is shared with students or external collaborators who don’t have Timeful accounts.

​
Authenticated User Sign-Ups

Signed-in users have their UserId stored in the SignUpResponse. The full User object is joined at query time for display purposes.

​
Creating a Sign-Up Form

1

Create a new event with sign-up mode

In the new event dialog, toggle on Sign-Up Form. Choose between Time Slots and Projects mode.
2

Define your blocks

Add each sign-up block with a name, optional start/end time, and capacity. The backend assigns MongoDB ObjectIDs to any blocks that don’t already have one.Example payload to POST /api/events:
{
  "name": "Linear Algebra Office Hours – Week 5",
  "type": "specific_dates",
  "duration": 0.5,
  "dates": ["2024-10-14T00:00:00Z"],
  "isSignUpForm": true,
  "signUpMode": "time_slots",
  "signUpBlocks": [
    {
      "name": "Slot 1",
      "capacity": 1,
      "startDate": "2024-10-14T14:00:00Z",
      "endDate": "2024-10-14T14:30:00Z"
    },
    {
      "name": "Slot 2",
      "capacity": 1,
      "startDate": "2024-10-14T14:30:00Z",
      "endDate": "2024-10-14T15:00:00Z"
    }
  ]
}
3

Share the sign-up link

Copy the generated event URL and share it with students or colleagues. They will see the available slots and can claim one directly from the page.
4

Monitor sign-ups

The event page shows which blocks have been claimed and by whom, along with remaining capacity for each block.

​
Columbia Math Department Use Cases

Office Hours

Professors and TAs define 20–30 minute time blocks. Students claim a slot to guarantee face time rather than waiting in a queue.

Advisor Meetings

Each meeting slot holds exactly one student. Advisors share the form at the start of each semester for registration advising.

Lab Equipment Booking

Research labs can expose equipment time as sign-up blocks with capacity ≥ 1 for shared instruments.

Reading Group Slots

Use Projects mode to let students self-assign to reading groups or problem-set teams with a defined group size cap.
Sign-up forms are a premium feature and are automatically available on all self-hosted Columbia Math Department deployments. See Premium Features.

Availability Polls

Use polls when you need participants to vote on a time rather than claim a pre-set slot.

Premium Features

All premium features including sign-up forms are unlocked by default on self-hosted deployments.

Build docs developers (and LLMs) love

Get started for freeTalk to us