Skip to main content
Some bookings need more than a 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.”
Reuse a client’s saved address. Each entry in a client profile’s addresses[] now carries latitude and longitude as well as the structured fields. That is everything a TRAVEL_ZONE booking needs, so you can book a visit to a saved address without geocoding it again. Either coordinate can be null when the address was saved without one; geocode those before booking.

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:
  1. POST /bookings with locationType: "TRAVEL_ZONE".
  2. A package session with locationType: "TRAVEL_ZONE" — whether that session arrives via the explicit sessions[] array on POST /orders/{orderId}/package-bookings, or is resolved for you inside a slate.
  3. The lat/lng branch of POST /availability/package-slate — i.e. when you pass lat + lng instead of a stored locationId.
  4. POST /holds, on any intervals[] entry with locationType: "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. (The slateId / slotIds forms of POST /holds need 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).
Omitting address on any of the four cases above fails validation with a 400 before the request does anything — there’s no fallback that derives an address from lat/lng for you. Reverse-geocoding is your integration’s responsibility (e.g. via a geocoding API), not MarketBox’s.

How it threads through slates

This is the detail worth understanding before you assume you need to resend address 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

A TRAVEL_ZONE booking created directly with POST /bookings — the address sits alongside latitude/longitude on the request body:
See Create a single booking for the full three-call flow this body belongs to.

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:
Every one of the 8 resolved 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.