Create Proposal
Create a new multi-party meeting proposal. Sends proposed time slots to one or more participants who can accept, counter, or reject. The authenticated user is automatically added as the organizer. ## Error codes - `400 earliest_slot_too_soon` — **poll mode only.** The earliest proposed slot starts within the minimum poll voting window (~25 hours from now). Propose a later earliest slot, or switch to `mode: standard`. - `403 consent_required` — at least one participant has not granted `booking:propose` to the originator. Establishing a network connection grants this automatically in both directions; if the participant has revoked it, the originator must wait for re-grant. - `409 calendar_disconnected_originator` — the authenticated originator has no active calendar connection. Reconnect a calendar before creating proposals.
Auth required: Yes
Idempotency-Key (header, string) — Unique key for idempotent POST requests (1-256 chars: alphanumeric, `_`, `-`, `:`, `.`).
Same key + same body within 24h replays the cached response.
mode: string — Proposal shape. `standard` (default) for account-keyed proposals; `poll` for magic-link voting.participant_ids: array — UUIDs of Vennio accounts to invite (1-10). **Required for `standard` mode; forbidden for `poll` mode.**
participant_emails: array — Email addresses of poll voters (1-10). **Only valid when `mode: poll`.** Non-empty produces a named poll (per-email magic links returned in `invitations[]`); empty/absent produces an open poll (single shareable `magic_link_url`).
slots: array (required) — Proposed time slots (1-10)message: stringmetadata: object — Extensible metadata (service_type, duration_minutes, price, etc.)expires_in_hours: integer — Hours until the proposal expires201: Proposal created. The response shape depends on `mode` and (for poll mode) whether `participant_emails` was supplied:
- **standard mode** → `StandardProposalCreated` — `{proposal}` only. Invitation emails are dispatched server-side; the caller does not receive magic-link URLs.
- **named poll** (`mode: poll` with non-empty `participant_emails`) → `NamedPollProposalCreated` — `{proposal, invitations: [...]}`. The caller owns voter messaging and gets one magic-link URL per named invitee.
- **open poll** (`mode: poll` with empty/absent `participant_emails`) → `OpenPollProposalCreated` — `{proposal, magic_link_url}`. A single shareable link; voters self-identify at vote time.
400: Validation error401: Authentication required or invalid409: A request with this Idempotency-Key is currently being processed422: Idempotency-Key was already used with a different request bodyRequires authentication. Pass a Bearer token (Supabase JWT) or an API key (`Authorization: Bearer vennio_sk_live_*`) in the request headers.
Base URL: https://api.vennio.app