Skip to main content
POST
Create a new booking

Authorizations

x-api-key
string
header
required

API key minted in the MarketBox dashboard. Scope is restricted to the projects you select at creation time. Every route needs the key's standard API access (*) except POST /v1/projects/{projectId}/events, which needs events:write; a key without * is refused with 403 CAPABILITY_NOT_GRANTED.

Path Parameters

projectId
string
required

The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.

Minimum string length: 1
Example:

"prj_01kv60qgnef2kt3pvqgwmkbzfr"

Body

application/json

Booking data

clientId
string
required

The client this booking is for.

Minimum string length: 1
Example:

"cli_01kv8p20m1gnqvxl92xln6awk8"

bookingStartUtc
string<date-time>
required

Start time in UTC (ISO 8601).

Example:

"2026-07-09T13:30:00.000Z"

bookingEndUtc
string<date-time>
required

End time in UTC (ISO 8601). Must be after start.

Example:

"2026-07-09T14:00:00.000Z"

bookingTz
string
required

IANA timezone the booking occurs in; local-time fields are derived from this.

Minimum string length: 1
Example:

"America/Toronto"

locationType
enum<string>
required

VIRTUAL, PHYSICAL, or TRAVEL_ZONE. Determines which location fields are required.

Available options:
PHYSICAL,
VIRTUAL,
TRAVEL_ZONE
Example:

"TRAVEL_ZONE"

services
object[]
required

One line per service booked; each draws down an order item.

Minimum array length: 1
supplierId
string

Assigned supplier. Omit to create an unassigned booking.

Minimum string length: 1
Example:

"sup_01kv60qgnef2kt3pvqgwmkbzfr"

locationId
string | null

For PHYSICAL: the Location id. For TRAVEL_ZONE: the supplierTravelZoneId. Null for VIRTUAL.

Minimum string length: 1
Example:

"stz_01kv60qgs4e4nbjhzradnqtj0h"

latitude
number | null

Client latitude. Required for TRAVEL_ZONE; must be omitted for PHYSICAL/VIRTUAL.

Example:

43.6532

longitude
number | null

Client longitude. Required for TRAVEL_ZONE; must be omitted for PHYSICAL/VIRTUAL.

Example:

-79.3832

address
object | null

Structured client address. Required for TRAVEL_ZONE bookings.

capacity
integer
default:1

Max participants for this booking.

Required range: x > 0
Example:

1

notes
object[]

Optional notes attached to the booking.

Response

Booking created

data
object
required