Connecting to a Meeting Space
Before you can push bookings to a meeting space, you must have an approved connection for that space in third_party mode. This is a one-time setup per space.
5.1 Step-by-Step
-
Org admin creates the meeting space (or picks an existing one) and sets its operating_mode to third_party. This is done inside ZenSpace — you do not do this.
-
Org admin issues an API key for your bridge. They share the plain key out-of-band.
-
Your bridge POSTs a connection request (see 5.2). This creates a connection in pending state.
-
The admin approves the connection in the ZenSpace admin UI. ZenSpace POSTs a notification to your webhook_url.
-
Your bridge starts pushing bookings once the approval webhook arrives.
5.2 POST /api/third-party/connection-request
The only endpoint external integrators call to register. All other connection-management endpoints (approve, decline, suspend, list, update, delete) are admin-only.
Field Reference
| Field | Type | Required | Notes |
|---|---|---|---|
| organization_id | UUID | yes | The organization that owns the space. |
| space_id | UUID | yes | Must belong to the organization, must already have a space group assigned. |
| third_party_mode | enum | yes | One of: Google Calendar, Outlook Calendar, Microsoft Outlook, Apple Calendar, Other. |
| detail | object | yes | Snapshot of your view of the space. |
| detail.name | string | no | Displayed if the ZenSpace space has no name. |
| detail.capacity | number | no | Seating capacity. |
| detail.timezone | IANA string | no | e.g. America/Los_Angeles. |
| detail.address | string | no | Street address. |
| detail.pricing.base_price | number | no | Only base_price is read during sync. |
| detail.business_hours | object | no | Map of weekday → { open, close } or null. |
| webhook_url | URL | strongly rec. | Where ZenSpace POSTs status-change and booking-event notifications. |
5.3 Approval Behavior
When the admin approves your request, ZenSpace does a one-way, non-destructive sync from your detail payload onto the meeting space. Only empty fields on the ZenSpace side are populated:
| detail field | Synced when ZenSpace side is... |
|---|---|
| name | null or empty |
| capacity | null / undefined / 0 |
| pricing.base_price | null or undefined |
| business_hours | no existing rows |
Send your best data up front. You do not get a second chance to overwrite unless the admin manually clears the field first.
5.4 Connection Lifecycle
The connection state machine:
-
pending → approved: booking events start flowing. Metadata sync runs.
-
pending → declined: terminal. To try again, submit a new request.
-
approved → suspended: booking events stop. Admin can re-approve later.
-
Only one approved connection per (space_id, third_party_mode) pair.