For the complete documentation index, see llms.txt.

POST /v1/bookings

Create Direct Booking

Create a booking directly without requiring a Venn Link. **Use Case**: Programmatic booking creation for platform integrations, AI agents, or custom scheduling interfaces. **What happens automatically**: - Calendar event created on business calendar - Confirmation emails sent to both parties - Webhook fired (`booking.created` event) - CRM sync triggered (if Salesforce/HubSpot connected)

Auth required: Yes

Parameters

• Idempotency-Key (header, string) — Unique key for idempotent POST requests (1-256 chars: alphanumeric, `_`, `-`, `:`, `.`). Same key + same body within 24h replays the cached response.

Request Body

• business_id: string (required)
• customer_email: string (required)
• customer_name: string (required)
• start_time: string (required)
• end_time: string (required)
• notes: string
• metadata: object — Developer-controlled key-value pairs (max 50 keys). Keys must be ≤40 characters, values must be strings ≤500 characters. Reserved keys (test_mode, demo_mode, customer_calendar_consent, booked_with_mutual_availability, price_amount, price_currency, meet_link, booked_by) are rejected.
• booking_answers: object — Pre-validated answers to booking questions, keyed by question ID
• recurrence: object — Optional recurrence configuration for creating a recurring booking series

Responses

• 201: Booking created successfully (single booking or recurring series)
• 400: Validation error
• 401: Authentication required or invalid
• 404: Resource not found
• 409: Resource conflict
• 422: Idempotency-Key was already used with a different request body
• 429: Too many requests

Authentication

Requires 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