TBBN.SpaceDocs
API

Space API guide

TBBN Space is "calendly for space" — a standalone product with its own public API for discovering and booking verified TBBN Spaces worldwide, independent of the TBBN marketplace. Any business or organization can search Spaces globally, embed that search/booking capability into their own product, and reserve a Space on behalf of their own clients — even clients who have no TBBN account at all.

This is deliberately a different surface from the marketplace's own Space picker (used when a trader is arranging a peer-to-peer trade exchange), which always defaults to a 200-mile radius and stays scoped to the marketplace's own trade flow. This guide's endpoints are unbounded (unless you ask for a radius) and open to any consumer, not just TBBN's own marketplace.

1. Global search — no account required

curl "https://api.tbbnetwork.com/v1/space/search?country=US&query=downtown"

Filters (all optional, combine freely): country, region (state/province), postalCode, lat+lng+radiusMiles (omit radiusMiles for unbounded-but-sorted-by-distance; omit lat/lng entirely for no distance filtering at all), query (free-text against the Space's name, its Branch's city, or the host Business's name). Each result is a Space — a single bookable room (a Branch can host several: "Study Room A," "Meeting Room B," etc.), not a whole Branch, so branchId and id (the Space's own id, used for booking) are both present on every result.

Visibility. A host sets each Space's visibility to PUBLIC (shown here to anyone), API_ONLY (never shown to an unauthenticated or session-only viewer — only returned when a valid sk_space_* key is presented), or RESTRICTED_EMAIL (only shown to a signed-in TBBN member whose verified email matches an exact allowlist or a domain, e.g. @cornell.edu, that the host configured). Search results are filtered to exactly what the presented credential is allowed to see — an unauthenticated call only ever sees PUBLIC Spaces.

2. Get an API key

Register a Business at business.tbbnetwork.com if you don't have one (any registered TBBN user can — a Business needs no Merchant relationship at all), then create a Space API key at account.tbbnetwork.com/space-api-keys?businessId=<your Business id>. You'll see the full key exactly once — store it like any other secret.

curl -X POST https://api.tbbnetwork.com/v1/space/api-keys \
  -H "Authorization: Bearer <your session token>" \
  -H "Content-Type: application/json" \
  -d '{"businessId": "biz_...", "environment": "SANDBOX"}'

Presenting this key on a search call (Authorization: Bearer sk_space_sandbox_...) applies your saved configuration automatically — no need to repeat your defaults on every request.

3. Configure default filters and "primary results"

curl -X PATCH https://api.tbbnetwork.com/v1/space/api-keys/<id>/config \
  -H "Authorization: Bearer <your session token>" \
  -H "Content-Type: application/json" \
  -d '{
    "defaultCountry": "US",
    "defaultRadiusMiles": 50,
    "pinnedBranchIds": ["branch_id_1", "branch_id_2"]
  }'
  • defaultCountry / defaultRegion / defaultRadiusMiles apply to any search call made with this key that doesn't explicitly override them.
  • pinnedBranchIds always sort first in search results (flagged isPinned: true) regardless of other filters — use this to feature your own preferred locations. (Pinning is by Branch id — a pin surfaces every Space at that Branch first.)
  • consentMode (STRAIGHT or REQUIRE_CONSENT) — see section 5.

4. Book on behalf of a real TBBN member

If the person being booked already has (or is willing to create) a TBBN account, have them authenticate normally and call POST /v1/space/bookings with spaceId (the specific room from your search results, not a branchId) and their own session token — this is the same booking flow the marketplace itself uses, and it always books+pays straight through (there's no consent step on this path — the booker is always the payer).

5. Headless booking — on behalf of a client with no TBBN account

Present your sk_space_* key instead of a session token, and include externalClientRef — your own opaque identifier for that client (never a TBBN identity):

curl -X POST https://api.tbbnetwork.com/v1/space/bookings \
  -H "Authorization: Bearer sk_space_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "spaceId": "space_...",
    "serviceType": "MEETUP",
    "externalClientRef": "your-internal-client-id-042"
  }'

You decide whether this needs an explicit consent step first. By default (consentMode: STRAIGHT, or requireConsent: false on the request) the response includes a paymentUrl straight away. Set your key's config to consentMode: REQUIRE_CONSENT (section 3), or pass "requireConsent": true on a specific booking, to instead get back a consentUrl: the booking is created AWAITING_CONSENT with no payment intent yet, and only after your client visits that link and accepts does the booking move to PENDING_PAYMENT and produce a real paymentUrl. This mirrors the TBBN marketplace's own rule that both parties must accept a Space before the person who picked it pays — third-party integrators choose which behavior fits their own product.

Redirect your client to whichever URL comes back (consentUrl or paymentUrl), or embed it in an iframe. Payment (and, when required, consent) always happens on TBBN's own hosted page — there's no way to collect that payment yourself and report it back. Once your client pays, the host is notified and can confirm the exchange — from their own space.tbbnetwork.com session, or via the same hosted payment link.

Even a free Space still requires this hosted step. If the host listed it as free (isFree: true), the booking's grossAmount is 0 and no charge happens, but your client still lands on the hosted page and must click through an explicit "Confirm free reservation" action before the reservation is finalized.

Production is currently running against a Stripe test key, so the hosted page shows a "Simulate payment" button rather than charging a real card — the integration itself is real and fully wired, so this is purely a which-key-is-configured detail, not something you need to build around.

Every booking also checks the same country/launch mechanism everything else on TBBN uses — a Space in a country not yet open for payments can't accept a booking at all.

6. Getting your Business verified

A Business does not need to be verified to create a Space — an unverified Business can create one exactly like a verified one; the only visible difference is an "Unverified" badge on its listing. Verification instead gates Merchant creation, a separate resource, not Space creation. Register at business.tbbnetwork.com to create a Business.

7. Team roles

More than one person can manage a Business's Spaces and API keys — invite teammates with a role (ADMIN, DEVELOPER, or ACCOUNT_MANAGER) at account.tbbnetwork.com/team?businessId=.... ACCOUNT_MANAGER can create/edit Spaces and pricing; DEVELOPER can create sandbox API keys and manage search/consent config (production keys need ADMIN); ADMIN can also manage the team itself. The Business's original creator is always the implicit OWNER and can do everything.

8. Liability for held items

A host can opt in to being liable for an item a trader drops off, capped at an amount they set — if they don't opt in, liability falls to the trader who dropped it off instead. Either way, a photo is taken and required at drop-off and again at pickup as the record either side relies on if something's disputed. A Space's search/detail response includes hostAcceptsLiability and liabilityCapAmount so your own UI can surface the real terms before someone books.

9. Receiving webhooks

Register a webhook subscription for Space booking lifecycle events — space_booking.created, space_booking.consent_required, space_booking.consented, space_booking.paid, space_booking.cancelled, space_booking.completed:

curl -X POST https://api.tbbnetwork.com/v1/webhooks/business-subscriptions \
  -H "Authorization: Bearer <your session token>" \
  -H "Content-Type: application/json" \
  -d '{"businessId": "biz_...", "url": "https://yourapp.example/webhooks/tbbn", "events": ["*"]}'

Deliveries are signed the same way as Merchant webhooks (x-tbbn-signature: t=<ts>,v1=<hmac>, verifiable with @tbbn/sdk-js's verifyWebhookSignature()) and retried up to 3 times before landing in DEAD_LETTER (replayable via POST /v1/webhooks/business-deliveries/:id/replay). You'll receive a delivery both when you're the host of the Space being booked and when you're the API-key holder who made a headless booking against someone else's Space.

What's not built yet

  • Space API monetization — general usage of this API is currently free. If TBBN introduces its own pricing for it, separate from Merchant SaaS billing, that will be documented in Pricing first.
  • Space tax collection/remittance — computed today, but as a placeholder that always returns $0; not a live tax integration yet.