GET /suppliers/{supplierId}for the profile, photo, rating, services and working pattern.POST /availability/suppliersfor the next time a client can book.
Read the supplier
Read one supplier
A supplier who can’t be shown
-
An unknown or deleted supplier is a
404. The same answer covers an id from another project:Render your own “not found” page. -
An inactive supplier is returned, with
active: false. The page still renders. Decide with the business whether to show a paused supplier, and don’t offer a time for one. -
active: truedoesn’t mean bookable. A supplier withavailability.schedules: []has no working hours. Only an availability search says when they’re free. See Show the next opening.
Show the photo
avatarUrl is one image: 256 × 256 pixels, WebP, cropped to fill the
square. It’s null when the supplier has no photo, so render a placeholder.
- The API exposes only this one URL. No field gives another size or format. Display it at up to 256 CSS pixels wide, or 128 on a high-density screen. Don’t build other sizes by editing the URL: its shape isn’t part of the API.
- The URL changes when the photo changes. The old photo’s images are
deleted when a new one is attached, so a stored old URL breaks. Cache
avatarUrlno longer than you cache the rest of the profile. - Removing the photo sets
avatarUrltonull.
Show the rating
The detail carriesrating: averageRating, reviewCount and the 5 newest
reviews in recent.
- Check
reviewCountbefore you render stars. An unreviewed supplier hasaverageRating: 0andreviewCount: 0. Render “No reviews yet”, not zero stars. - Strip the reviewers’ details. Show what the business agrees to, such as the stars, the text and a first name.
- For the badge alone,
GET /suppliers/{supplierId}/review-summaryreturns justsupplierId,averageRatingandreviewCount. Use it to refresh the rating without re-reading the whole profile.
List the services
services[] lists what the supplier offers: each entry is a serviceId and a
name.
- Only
LIVEservices appear. A supplier mapped to aDRAFTorINACTIVEservice doesn’t list it. nameis keyed by language, such as{ "en": "Deep tissue massage", "fr": "Massage des tissus profonds" }. Pick the client’s language, and fall back to one the service has.- There are no prices or durations. Those live on the service’s offerings.
Read them with
GET /services/{serviceId}/offerings?status=ACTIVE. Amounts are integer minor units, so4500is $45.00, and the price can depend on where the session happens. See Offerings and Regional pricing.
The working pattern
availability.schedules[] is when and where the supplier works, such as
“Mon, Wed, 9:00 AM – 5:00 PM” from each schedule’s summary. Show it as
working hours, not as free times: it ignores bookings and time off. See
Availability is a pattern, not a list of times.
Show the next opening
No availability route takes asupplierId for one supplier’s single sessions.
POST /availability/suppliers returns every supplier who serves the service at
the place you ask about, a page at a time.
To find one supplier’s next opening, page through the results until their
entry appears:
- Choose the place. The search needs a
locationId, orlatandlng. For a supplier who works at a venue, send thelocationIdof aPHYSICALentry in theirlocations[]. For one who travels to clients, send the client’s address aslatandlng. Without a client address, show the working pattern instead of a time. days: []means nothing is free in the window. The supplier serves the offering there, but every slot is taken. Say “No times in the next two weeks”, or search again with a largerlookAheadDays.- Not in any page usually means not offered here. The supplier doesn’t serve that offering at that place, or isn’t searchable right now, such as a paused supplier.
- Check
errorson each page. A page can come back200with messages inerrors, when part of the search couldn’t be computed. Treat a missing supplier on such a page as unknown, not as “not offered”. - The time can be taken before the client books. An open slot isn’t a hold. Re-check when the client picks it, or hold it. See Hold slots during checkout.
x-mb-client-kind: server header tags
these lookups as your server’s. See
Report site events. For the request fields and
the response in full, see
Search suppliers by availability.
For a package,
POST /availability/package-slate and
POST /availability/package-options do take a supplierId, and plan the
package’s sessions with that supplier only. See
Create a package booking.Put it together
Build the public profile on your server, and return only this to the browser:profile_view event, so the
supplier’s insights count the visit. See
Report site events.
Reference
Endpoints used in this guide
Errors and edge cases
See Errors for the envelope and every code.