latitude/longitude pair — they need a real,
structured street address a supplier can navigate to. This guide covers the
address object: its shape, exactly when it’s required, and how it flows
through slates so you usually only have to supply it once.
It builds on The booking engine model. If
you haven’t yet, read Create a single booking
or Create a package booking first — this
page assumes you’re already creating bookings or slates and just need the
address piece. To let a client save addresses and choose a default, see
Manage a client’s account.
The address object
address is a structured object, not a free-text string — every field below
is validated independently so a supplier’s app can render it, geocode it, or
hand it to a maps SDK without re-parsing anything.
zipCode accepts any format — it’s a plain string, not validated against a
country-specific pattern. country is the odd one out: it’s the only field
that is rejected when it can’t be resolved. MarketBox converts an alpha-3
code or English name to alpha-2 before storing it, so you read back "CA"
whichever you sent. A country it can’t resolve is a 400 VALIDATION_ERROR.
state is converted to its ISO 3166-2 code ("Ontario" becomes "ON")
when it can be, and is kept as you typed it otherwise. Everything else is
just “non-empty string.”Where it’s required
address is only required where a booking’s location is a travel zone —
a supplier traveling to the client, resolved from latitude/longitude
rather than a stored Location record. It’s rejected as unnecessary nowhere,
but it’s validated as mandatory in exactly four places:
POST /bookingswithlocationType: "TRAVEL_ZONE".- A package session with
locationType: "TRAVEL_ZONE"— whether that session arrives via the explicitsessions[]array onPOST /orders/{orderId}/package-bookings, or is resolved for you inside a slate. - The lat/lng branch of
POST /availability/package-slate— i.e. when you passlat+lnginstead of a storedlocationId. POST /holds, on anyintervals[]entry withlocationType: "TRAVEL_ZONE". A hold mirrors the booking contract exactly, because convert rebuilds the booking from the hold alone — so an in-home session’s address must be on the hold, not supplied later. (TheslateId/slotIdsforms ofPOST /holdsneed no address: the slate already stamped one onto every slot.)
VIRTUAL and PHYSICAL bookings never take an address at all — VIRTUAL
has no location fields, and PHYSICAL resolves everything from the stored
Location record (see the location-rules table in
Create a single booking).
How it threads through slates
This is the detail worth understanding before you assume you need to resendaddress at every step of a package flow — you don’t.
address is captured once, at slate-build time, on the lat/lng branch of
POST /availability/package-slate. The engine then stamps that same
address onto every persisted slot in the slate (slots[].address), whether
the slot’s session is 1 of 8 or 8 of 8. When you later book with
{ orderItemId, idempotencyKey, slateId }, the server re-resolves each session from its
persisted slot — address included — so the TRAVEL_ZONE address rule on
POST /orders/{orderId}/package-bookings is satisfied automatically. You
never pass address a second time on the booking call itself.
The one place this doesn’t apply automatically is the transcribe path
(Path A in Availability and slates):
if you build your own sessions[] array instead of sending slateId, you
must copy address off each slot verbatim, the same as every other
location field — the server has no persisted slate to fall back on when
you’re supplying sessions explicitly.
Example: single booking
ATRAVEL_ZONE booking created directly with POST /bookings — the
address sits alongside latitude/longitude on the request body:
Example: package slate
A slate built on the lat/lng (travel-zone) branch —address is a sibling of
lat/lng, not nested inside a location object:
slots[] in the response carries this same
address. Book the slate with { orderItemId, idempotencyKey, slateId } — no address field
on that call at all. See
Create a package booking for the full
flow this body belongs to.
Reference
Where address is required
Not required — and not accepted as a substitute for anything — on
VIRTUAL
or PHYSICAL bookings or holds, or on the locationId branch of
package-slate.
Errors and edge cases
See Errors for the full envelope and code list.