curl, or Node 18 or newer for the TypeScript ones.
1. Get a project and an API key
Everything in the API belongs to a project, and an API key is minted inside one. You do this once, in the MarketBox dashboard.1
Sign up or sign in
Open the dashboard. It sends you to
the MarketBox sign-in page. If you have no account yet, sign up there with
your email address.
2
Create a project
A new account lands on a home page with a Set up your business card:
select it. If you already belong to a project, select New project
instead.Enter a Project name, Time zone, Language and Slug, then
select Create project. You become the project’s admin.
3
Create an application
In the project, open Settings in the sidebar, then API Access under
Operations. Only a project admin can open this page.Select New application and fill in:
- Application name: a label for this integration.
- Callback URLs and Logout URLs: both are required. They belong to
end-user sign-in, which this quickstart doesn’t use. Enter
http://localhost:3000/auth/callbackandhttp://localhost:3000/for now, and see Build a booking flow when you add sign-in. - What the API key may call: leave Standard API access ticked. A key
without it is refused with
403 CAPABILITY_NOT_GRANTED.
4
Copy the API key
The page shows Copy the API key now — it’s shown only once. Select
Copy key and store the key somewhere safe. It can’t be shown again: if
you lose it, mint a new one.
5
Copy the project ID
On the application, Config for this booking flow lists
projectId and
apiBaseUrl, with the sign-in settings. Copy config copies them all.The project ID starts with prj_. It is also in the address bar on every
page of the project: /dashboard/project/prj_…/.2. Make your first call
The MarketBox API is served from:MARKETBOX_API_URL:
This is the production API. A key acts on the real data of its project. See
Test keys and sandbox.
x-api-key header. Health is the
simplest endpoint to verify connectivity — it’s unauthenticated and lives
outside /v1.
data is an empty array. That is
still a working call: your key and project ID are right. Step 3 says how to
add a service.
Once you have a service, list its offerings. An offering is a bookable
variant of a service, with its own duration and price:
3. Create a booking
What a booking needs
A booking names a service and offering, a supplier, a client and a time. A new project has none of these, so create them first:
A client is created in one of two ways:
- A person signs in through your booking flow.
POST /clients/mewith their token creates the client and returns theclientId. That is the production path: see Build a booking flow. - Staff add the client in the dashboard. This is the quick way for a
first test. In the project menu, open Customers, which is the
dashboard’s name for clients. Choose New customer, fill in the form,
then choose Open full profile. The
cli_ID is the last part of the page address:/dashboard/project/prj_…/client/cli_….
Create the order
A booking always draws down an order item: you can’t create one without an order first. Create an order with oneSINGLE_SESSION item for your
service and offering. Send the currency of the offering’s price from
step 2.
data.order, and its items under data.items[].
The created order is DRAFT and unpaid. That is enough to book against: see
Accept payments with Stripe to charge
for it later.
Create the booking
Each service line references theorderId and orderItemId from the order
you just created. This is what ties the booking back to what paid for it.
The body also carries explicit UTC timestamps plus an IANA timezone, and
MarketBox derives the local date and times for you (see
Timezones). This example uses
locationType: "VIRTUAL", which needs no other location fields. PHYSICAL
and TRAVEL_ZONE bookings need more: see
Create a single booking for the required
fields per locationType.
data, with status: "SCHEDULED"
and the bookingId you use for follow-on actions. To undo a test booking,
cancel it: see
Cancel or reschedule a booking.
If it fails
Create a single booking
has the full list.
4. Handle errors
Every error response has the same envelope:requestId is also returned in the X-Request-Id response header —
include it when contacting support. See Errors for the
full code list.
Next steps
Authentication
How API keys, project scope, and tenancy work.
Pagination
Cursor-based pagination on the large list endpoints.
Resources
Per-resource overviews of bookings, orders, offerings, and suppliers.
API reference
Every endpoint with an interactive playground.