Signups

Create a new signup

Subject to the per-org daily ceiling (50 signups created per day, regardless of tier). Pass an Idempotency-Key header to make retries safe.

post/signups

Request

  • Base URL: https://thesignup.app/api/v1
  • URL: https://thesignup.app/api/v1/signups
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

Opaque client-supplied key, ≤ 200 chars. Same key + same body within 24h returns the original response. Same key + different body returns 422.

Request body

titlestring required
descriptionstring
locationstring
eventDatestring required

ISO-8601 datetime. Either UTC (...Z) / offset-bearing, OR a naive local string (2026-09-15T17:00) — naive form requires timezone to also be set; the server then interprets the string as wall-clock time in that zone.

signupCloseDatestring

ISO-8601 datetime, same rules as eventDate. Defaults to never (signups stay open until the event).

timezonestring

IANA timezone name (e.g. America/Los_Angeles). When provided, naive eventDate/signupCloseDate/slot times are parsed against this zone, and the value is stored on the signup so display surfaces can render the organizer's wall-clock intent.

maxParticipantsinteger
requiresPhoneboolean

Default false.

isPrivateboolean

Default false.

Example request

{
  "timezone": "America/Los_Angeles"
}

Response

Signup created

idstring uuid required
organizationIdstring required
slugstring required
titlestring required
status'draft' | 'published' | 'closed' required
eventDatestring date-time required

ISO-8601 UTC.

signupCloseDatestring date-time nullable required

ISO-8601 UTC. Null = signups never close until the event.

locationstring nullable required
isPrivateboolean required
createdAtstring date-time required
updatedAtstring date-time required
descriptionstring nullable required
maxParticipantsinteger nullable required

Cap on total participants. Null only on a plan with no participant ceiling (uncapped); elsewhere the cap is stored as the plan ceiling.

commitmentRequiredboolean required

When true, a participant must claim a slot or an item to sign up — attending without committing to anything is not offered.

requiresPhoneboolean required
timezonestring required

IANA timezone the organizer attached to this signup. Display surfaces should prefer this over the viewer's local zone when rendering eventDate / slot times.

Example response

{
  "id": "550e8400-e29b-41d4-a716-446655440100",
  "organizationId": "org_123",
  "slug": "fall-fundraiser-a1b2",
  "title": "Fall fundraiser",
  "status": "published",
  "eventDate": "2026-09-15T17:00:00Z",
  "timezone": "America/Los_Angeles"
}

Changes

No recorded changes to this operation across all 1 revision of this API.