Skip to main content
A supplier is the entity that fulfills a booking — typically a person, but conceptually any unit of capacity (a stylist, a doctor, a tutor, a meeting room). There are two ways to read one, and picking the right one matters: 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:
active and bookability are set independently. A supplier can be active: true and still be impossible to book, because they have no live schedule. The reliable check is availability.schedules.length > 0, and the only authoritative one is asking the availability engine for real times.

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

The locations[] 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/ and ca/on/toronto/, so country=CA alone 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/ and ca/on/toronto/, so city=Scarborough and city=Toronto both 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

The response carries the supplier’s email, phone and address. Don’t pass it straight to a browser: copy the fields your page renders.
To assemble a public profile from this response, see Build a supplier profile page. An inactive supplier is returned, with 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 carries access. 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.
So it cannot tell you a time is free. Never present a time built from 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 from rrule. The rule decides which weeks; the array decides which days. A weekday absent from the array is a day this supplier does not work.
  • crossesMidnight must be checked before comparing times. A night shift is startTime: "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, then state, then city. Hierarchical, and each level requires the one above: state without country is a 400, as is city without 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 with services/skills.
Sending 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.
A point only matches travel zones. A supplier whose live schedules are all at fixed locations has no zone and is never returned by lat/lng, even if the point is their own studio. Use the region filter, or POST /v1/projects/{projectId}/availability/suppliers with a locationId, for fixed-location suppliers.
Only active suppliers are listed; inactive and deleted ones never appear, on any combination of filters. With no filter, results are in name order (last name, then first name). With a service, skill or 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:
Read the supplier again, then retry if the photo still isn’t the one you want. A 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: false with PUT instead.
A 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

See Bookings.

Endpoint index

  • GET /v1/projects/{projectId}/suppliers
  • GET /v1/projects/{projectId}/suppliers/{supplierId}
  • POST /v1/projects/{projectId}/suppliers
  • PUT /v1/projects/{projectId}/suppliers/{supplierId}
  • DELETE /v1/projects/{projectId}/suppliers/{supplierId}
  • GET /v1/projects/{projectId}/suppliers/{supplierId}/bookings
  • GET /v1/projects/{projectId}/suppliers/{supplierId}/review-summary
  • POST /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-url
  • PUT /v1/projects/{projectId}/suppliers/{supplierId}/avatar
  • DELETE /v1/projects/{projectId}/suppliers/{supplierId}/avatar
  • POST /v1/projects/{projectId}/availability/suppliers
  • GET /v1/projects/{projectId}/skills — see Locations and skills
  • The supplier plane, /v1/projects/{projectId}/suppliers/me and below — see Build a supplier portal