The detail endpoint is a superset. The list omits
rating and availability
on purpose — each costs an extra read per supplier, and a 200-row page should
not pay for data a directory does not show.
Both answer for your application, with the API key alone. A supplier
managing their own profile, bookings and hours through your portal uses the
supplier plane instead — /v1/projects/{projectId}/suppliers/me, with the
supplier’s user token. See The supplier’s own view.
Booking identity
A supplier response is not just display content. These are the fields you need to actually book against a supplier, and where each one lives:Anatomy
Every supplier response — list row or detail — carries these. Profile fields, selected from the full supplier record:
Enriched mappings, joined against the project’s catalog and schedules:
Both
services and skills carry localized name maps. If your project’s
services are named in several languages, the response contains all of them —
pick the locale you want client-side.
Only bookable catalog is joined in. A mapping to a service that is not
LIVE,
or to an inactive skill, is dropped from the array entirely rather than
returned with a blank name. So services is what this supplier can actually
be booked for today, not a historical record of what they were ever assigned.Timezone
timezone is the supplier’s own IANA zone, and it is optional on the
profile — a project whose suppliers all work in one place often leaves it
unset.
On create and update it must be an IANA identifier such as America/Toronto;
an abbreviation like EST or an offset is a 400 VALIDATION_ERROR (see
Timezones). The value does real work:
it decides when the supplier’s daily agenda email fires, and availability
responses report it in supplierZones as the fallback bookingTz for
virtual bookings. Unset inherits the project’s default timezone.
The list endpoint returns it as-is, absent and all. The detail endpoint
additionally resolves it for you:
timezoneSource tells you whether that value is real. SUPPLIER means it came
from the profile. PROJECT means the profile had none and the project default
was substituted — a sensible display default, but not a statement about where
this supplier works. Do not derive travel logic from a PROJECT-sourced zone.
See Timezones for how booking times are rendered.
Locations
Thelocations[] array is derived from the supplier’s schedules — not
stored on the supplier record. A location nobody is scheduled at is not
somewhere you can book, so it does not appear.
Each schedule contributes locations through three reference shapes:
Locations are deduped by
locationId. References that do not resolve (a
deleted location, a missing travel zone) are skipped silently rather than
surfaced as nulls.
Each location record:
Only live schedules contribute. A schedule is live when it is
ACTIVE, not
deleted, and its endDate has not passed in the schedule’s own timezone. That is
the same rule the list’s region filter, servedRegions and the detail endpoint’s
availability.schedules use, so the four never disagree about whether a
supplier can be booked. A supplier with no live schedule has locations: [] —
including one whose only schedule ended last week.
Regions served
servedRegions is the answer to “why is this supplier (not) returned by
country=CA&state=ON&city=Toronto?”. It is the list of region paths the
supplier is indexed under — the same set the list’s location filter
matches against, so a supplier is returned by that filter exactly when the
query’s path is in this array.
- Slug paths at every level of the hierarchy, sorted. A zone in Toronto
contributes
ca/,ca/on/andca/on/toronto/, socountry=CAalone matches it. - Derived from the travel zones and physical locations on the supplier’s
live schedules — the same sources as
locations[]. - A zone inside a borough is indexed under the locality, the borough and
the wider municipality. A Scarborough zone carries both
ca/on/scarborough/andca/on/toronto/, socity=Scarboroughandcity=Torontoboth return it. []when the supplier has no live schedule with a geocodable zone.
locations[] is evaluated on every request; servedRegions is maintained by
an index that a daily sweep prunes. For up to a day after a schedule’s
endDate passes, a supplier can therefore still carry the region in
servedRegions (and still match the filter) while locations[] has already
dropped it. Treat locations[] as the fresher of the two.Reading one supplier
active: false, so a profile page
for a paused supplier still renders. This differs from the list, which hides
them. A 404 means the id is unknown in this project, belongs to another
project, or has been deleted — those three are not distinguished.
Who can sign in as this supplier
Only the detail read carriesaccess. GET /suppliers and
POST /availability/suppliers don’t. It says whether the record is linked to a
person who can sign in to your portal, and what that person holds on the
project:
Removing a supplier’s
SUPPLIER role unlinks the record, so invitationStatus
goes back to NONE. accessEndedAt tells the two NONEs apart: set means
the supplier was removed, null means they were never invited. A supplier
removed before November 5, 2026 has null. See
Removed, or never a supplier.
access is read-only. The business invites and removes suppliers in the
dashboard.
Rating and reviews
rating is read from an aggregate maintained in the same atomic write that
records each review, so it never disagrees with the rows behind it.
A supplier nobody has reviewed returns
averageRating: 0 and reviewCount: 0
— check reviewCount before rendering stars, or an unrated supplier displays
as a zero-star one.
recent is a preview, not the full set. To page through every review, call
GET /v1/projects/{projectId}/reviews with supplierId. See
Reviews. No email address is returned for either party.
If the rating badge is all you need and you are not rendering a whole profile,
GET /v1/projects/{projectId}/suppliers/{supplierId}/review-summary returns
just the aggregate. See
Collect reviews and show ratings
for a badge, a profile page and the full list.
Availability is a pattern, not a list of times
This is the single most expensive thing to get wrong on this endpoint.availability.schedules[] describes when and where this supplier works. It
is the recurring pattern an operator configured. It knows nothing about:
- bookings already on the calendar,
- time off,
- how long the offering you want to sell actually takes.
weeklyHours as available. For times you can genuinely book, call
POST /v1/projects/{projectId}/availability/suppliers with a service, an
offering and a location — see
Search suppliers by availability.
What the pattern is good for: rendering “Mon, Wed 9–5” on a profile, deciding
whether to show a supplier at all, and telling a client the earliest week worth
asking about.
Reading a schedule
Two traps in
weeklyHours:
- The weekdays come from
weeklyHours, not fromrrule. The rule decides which weeks; the array decides which days. A weekday absent from the array is a day this supplier does not work. crossesMidnightmust be checked before comparing times. A night shift isstartTime: "22:00",endTime: "02:00",crossesMidnight: true. Compare the two strings without it and you get a negative-length day.
travelZone.source distinguishes a zone drawn for this supplier alone
(SUPPLIER_TRAVEL_ZONE, an stz_ id) from a project-wide zone several
suppliers share (PROJECT_LOCATION, a loc_ id). Search finds a supplier in
either kind of zone, but only a supplier’s own zone can be booked at a client’s
address: a TRAVEL_ZONE booking’s locationId must be an stz_ id, and a
loc_ id is 404 NOT_FOUND. See
Set up a mobile supplier’s service area.
Only live schedules are returned — ACTIVE, not deleted, and endDate not
yet passed in the schedule’s own timezone. schedules: [] means the supplier
cannot currently be booked at all, whatever active says.
A schedule’s start and end of day locations are never returned here, or in
any availability response. In the public API, you read and write them on the
supplier plane.
Listing suppliers
Every filter is AND, both within a parameter and across them.
services=srv_a,srv_b means a supplier offering both, never either.
There are two ways to filter by place, and they are exclusive:
- By region —
country, thenstate, thencity. Hierarchical, and each level requires the one above:statewithoutcountryis a400, as iscitywithout both. - By point —
lat+lng, both or neither. Returns every supplier whose live travel zone contains that point, tested against the zone’s actual polygon or radius rather than a place name, and AND-combined withservices/skills.
lat/lng together with any of country/state/city is a 400.
Both filters match the regions a supplier serves — derived from the travel
zones and physical locations on their live schedules — not the address on
their profile. A mobile supplier based in Barrie whose travel zone covers
Toronto matches
city=Toronto. A supplier with an address but no live
schedule matches nothing, because they cannot be booked. Coverage resolves to
the locality, its borough and the wider municipality, so a Scarborough zone is
returned by city=Scarborough and by city=Toronto. Each row’s
servedRegions is the exact list the region filter checked — see
Regions served.lat/lng filter, they are
ordered by supplier id. With only a country, state or city filter, they follow
the location index, so don’t rely on any particular order.
Treat nextCursor: null as the only end-of-results signal — never stop on
a page that merely looks short. A cursor is valid only against the filter set
that produced it; change a filter mid-walk and restart.
Every page of one listing carries the same searchId (also the
X-MB-Search-Id header; the cursor keeps it), and each row a 0-based
position, continuous across pages. If you draw the list for clients, report
it with that searchId so suppliers’ insights count it. See
Report site events.
Managing suppliers
Supplier management is normally done in the MarketBox dashboard, but the public API exposes it too, so you can keep a roster in sync from your own system:
Use
externalId to carry your own primary key onto the supplier, so you can
reconcile without storing a second id map.
For the whole setup in order, from service to bookable supplier, see
Provision your catalog and suppliers.
Three profile fields have write rules worth knowing:
An unparseable phone or a malformed locale is a
400 VALIDATION_ERROR — the
row is not written.
email is unique within the project. A POST or PUT that uses another
supplier’s email is 409 CONFLICT, “A supplier with this email already exists
in the project”, and nothing is written.
A PUT that sends active is also 409 CONFLICT when active changed
between the update’s read and its write: “This supplier’s Active setting
changed while it was being saved. Reload and try again.” Read the supplier
again, then retry if your change still applies.
The avatar routes answer the same way. A PUT or DELETE on
/suppliers/{supplierId}/avatar is 409 CONFLICT when another confirm or
remove changed the photo while this one was being saved:
DELETE is permanent around the edges, even though the profile itself is
only soft-deleted and stays readable to the bookings that reference it:
- Every service and skill mapping is hard-deleted, and the avatar images are removed.
- The supplier’s sign-in loses its supplier role.
- Existing bookings are not cancelled or reassigned. Deal with the supplier’s diary first.
- There is no undelete. To take a supplier off the roster for a while, set
active: falsewithPUTinstead.
DELETE that races a change to the supplier’s sign-in, such as the supplier
accepting an invitation at that moment, is 409 CONFLICT, “This supplier’s
sign-in changed while it was being deleted. Try again.” Nothing was deleted;
send the DELETE again. A PUT with "phone": "(416) 555-0134" reads back as
"phone": "+14165550134".
Schedules are not writable with the API key alone. A supplier created here
has no schedule, so availability.schedules is [] and they cannot be booked
until working hours are set — by an operator in the dashboard, or by the
supplier themselves through your portal, on the
supplier plane.
The supplier’s own view
The supplier plane lets a supplier who signs in to your portal act on their own record: their profile and photo, their bookings and attendance reports, cancelling and moving bookings when the service allows it, their working hours, blocked time and travel zones, their demand and search insights, and their alerts. Every route sits under/v1/projects/{projectId}/suppliers/me and takes both
the API key and the supplier’s user token. The API never takes a supplier id
there: me is the supplier the token belongs to. See
Build a supplier portal.
GET /v1/projects/{projectId}/suppliers/me returns the supplier’s own record
as the MarketBox dashboard shows it. It adds serviceIds and skillIds, the
raw assignments, where the public endpoints return only the joined services
and skills.
GET /v1/projects/{projectId}/suppliers/me/access tells your portal, on
sign-in, whether the person may use the supplier plane at all, and why not.
See Check access first.
Bookings for one supplier
Endpoint index
GET /v1/projects/{projectId}/suppliersGET /v1/projects/{projectId}/suppliers/{supplierId}POST /v1/projects/{projectId}/suppliersPUT /v1/projects/{projectId}/suppliers/{supplierId}DELETE /v1/projects/{projectId}/suppliers/{supplierId}GET /v1/projects/{projectId}/suppliers/{supplierId}/bookingsGET /v1/projects/{projectId}/suppliers/{supplierId}/review-summaryPOST /v1/projects/{projectId}/suppliers/{supplierId}/services/{serviceId}DELETE /v1/projects/{projectId}/suppliers/{supplierId}/services/{serviceId}POST /v1/projects/{projectId}/suppliers/{supplierId}/skills/{skillId}DELETE /v1/projects/{projectId}/suppliers/{supplierId}/skills/{skillId}POST /v1/projects/{projectId}/suppliers/{supplierId}/avatar/upload-urlPUT /v1/projects/{projectId}/suppliers/{supplierId}/avatarDELETE /v1/projects/{projectId}/suppliers/{supplierId}/avatarPOST /v1/projects/{projectId}/availability/suppliersGET /v1/projects/{projectId}/skills— see Locations and skills- The supplier plane,
/v1/projects/{projectId}/suppliers/meand below — see Build a supplier portal