Skip to main content
The supplier plane lets a supplier who signs in to your portal do what they do in the MarketBox dashboard:
  • keep their profile and photo up to date;
  • see their bookings and file attendance reports;
  • cancel or move a booking, when the service allows it;
  • set their working hours, blocked time, travel zones and venues;
  • read their demand and search insights;
  • see and clear their alerts: new, moved and cancelled bookings.
Every route lives under one base path, and none of them names a supplier:
me is the supplier the user token belongs to. The API never reads a supplier id from the path or the body. A booking, schedule, blocked time or travel zone id that isn’t theirs is a 404 — the same answer as an id that doesn’t exist.
The dashboard and your portal run the same code. Every supplier-plane route is the twin of a dashboard route, with the same rules. A supplier gets the same answer, and the same refusal, from both.
A supplier portal signs in exactly as a booking flow does. For what is specific to suppliers, start with Sign-in and access.

The pages of this guide

Three task guides go deeper on the same plane:

First sign-in: set the supplier up

A supplier who signs in for the first time may have no hours yet. Set them up in this order. The /suppliers/me calls take the API key and the supplier’s access token. The service list and the availability check take the API key alone.
1

Check access

GET /suppliers/me/access answers 200 with allowed and a reasonCode. Go on only when allowed is true; otherwise show its message. See Check access first.
2

Read the profile

GET /suppliers/me returns the supplier’s own profile, including timezone and serviceIds. See Edit the profile.
3

Set the timezone

PATCH /suppliers/me with timezone. Hours and blocked time take the profile zone when you omit timezone on create. When neither the profile nor the project has a zone, the create is a 400 BAD_REQUEST. See Times.
4

Set the services

PATCH /suppliers/me with serviceIds, taken from GET /v1/projects/{projectId}/services?status=LIVE. A schedule’s serviceOfferingIds must be ACTIVE offerings of these services. You can send timezone and serviceIds in one PATCH.
5

Choose where they work

For in-home work, create the supplier’s own travel zone with POST /suppliers/me/travel-zones. See Set up a mobile supplier’s service area. For a venue, pick one from GET /suppliers/me/locations. See Venues.
6

Create the schedule

POST /suppliers/me/schedules with the hours, naming the zone in travelZoneRef or the venue in locationRefs. A travel zone on its own makes no one bookable. See Set working hours. If the project uses start and end of day locations, the schedule can also carry where the supplier’s day starts and ends. See Start and end of day locations.
7

Check what clients are offered

POST /v1/projects/{projectId}/availability/suppliers takes the API key alone, so your server can run it after the supplier saves. Find the supplier by supplier.supplierId and read their open days. Search updates shortly after a schedule is saved, so allow a short delay. See Check the result.

Times

  • A booking’s time is an instant plus a zone. bookingStartUtc and bookingEndUtc are UTC instants. bookingTz is the booking’s home zone, and bookingLocalDate, bookingLocalStartTime and bookingLocalEndTime are the same times in that zone. Show the booking in its home zone, labelled.
  • A reschedule carries one UTC instant, the new startTime. The booking keeps its length, and its local times are worked out again in its own zone.
  • Hours and blocked time are wall-clock rules: HH:MM times and YYYY-MM-DD dates in the row’s timezone, with a weekly rrule. Omit timezone on create to use the supplier’s profile zone, or the project’s default zone when the profile has none. When neither exists, the create is a 400 BAD_REQUEST. An update keeps the row’s stored zone.
  • Insights are given in the supplier’s home zone.
  • Query windows on bookings (startDate, endDate) are UTC instants.
See Timezones.

Not on the supplier plane yet

These dashboard features have no supplier-plane route yet. Suppliers use the dashboard for them:
  • Google Calendar — connecting a supplier’s calendar.
  • Invitations — inviting a supplier into the project. A supplier accepts once in the dashboard, then signs in to your portal with the same account.
For everything else the API can’t do yet, see What the API doesn’t do.

Reference

Endpoints used in this guide

Every route on the supplier plane takes the API key and the supplier’s access token. Key-only routes the portal also uses, with the API key alone: