- a review — a 1–5 star rating with optional text, written in either direction: a client rating the supplier who served them, or a supplier rating the client.
- a report — one side stating a fact about the booking. Today the only fact is attendance: “I showed up”.
Direction is the thing to get right
A review always names both parties, and which one is being rated depends on the direction:
Rather than apply that table yourself, read the two derived fields every review response carries:
subjectType—SUPPLIERorCLIENTsubjectId— the id of whoever is being rated
direction and are reported as CLIENT_TO_SUPPLIER.
How it works
Your page calls MarketBox from your server, never the browser: the API key is a server-only secret. See Authentication.What MarketBox puts in the link
SetreviewRedirectUrl in your project’s notification settings and MarketBox sends recipients
there instead of to its own page. It appends its own query parameters to whatever URL you
configure, merging them into any query string already present:
Treat these leniently. Ignore parameters you do not recognise, and expect new ones to appear
over time;
role itself was added after bookingId. Nothing that was already sent has changed
meaning.
If your URL contains the literal token {bookingId}, MarketBox substitutes it and still appends
the bookingId parameter. You get the id twice on purpose — parse whichever you prefer.
{bookingLocale}, {clientLocale} and {supplierLocale}, are substituted
the same way and each falls back to the project’s default locale. See
Emails for what each one resolves to.
role tells you who is standing in front of you
One booking produces two different asks, and both land on the same URL:
Without it your page cannot tell the two apart from the booking id alone, and would show one side
the other side’s form. If
role is missing or unrecognised — an old link, a hand-edited URL —
fall back to your own signed-in context rather than guessing; do not default to client.
role says which side was emailed, not which side is authenticated. It is a routing hint in a
URL anyone can edit, so keep authorising the submission the way you already do.
Leaving a review
1
Resolve the booking
Your page is given a
bookingId. GET /v1/projects/{projectId}/bookings/{bookingId} returns
the booking, including clientId, supplierId and the local date and time. You never send
those ids back — MarketBox reads them off the booking itself.2
Collect a rating
A whole number from 1 to 5, plus optional text up to 5000 characters.
3
Post it
Leave a review
201 Created
4
Show what is already there
GET /v1/projects/{projectId}/bookings/{bookingId}/reviews returns every review linked to
the booking, newest first, so a returning visitor sees their own rating rather than an empty
form.supplierName and clientName alongside the ids, so a page can render a name
without a second call. The project-level POST /reviews and GET /reviews are the exception: they
return the ids only. They are best-effort: a counterparty whose profile cannot be resolved keeps
its bare id and the name fields are simply absent. No email address is returned for either party.
Those names only exist once a review does, which is backwards for a page whose job is collecting
the first one. Before any review exists, get both display names from
GET /v1/projects/{projectId}/bookings/{bookingId}/aggregate in a single call — its parties
object carries parties.client.fullName and parties.supplier.fullName, which is the only way to
turn a clientId into a name (there is no public client read endpoint).
One review per booking per direction
The two sides are independent — a booking can hold one client-to-supplier review and one supplier-to-client review — but a second review in the same direction returns 409REVIEW_ALREADY_EXISTS. Uniqueness is enforced inside the same write as the review, so two
simultaneous submissions cannot both win.
Treat a review as permanent. There is no update or delete route, and the rating it contributes to
the subject’s average is not reversible.
Two ways to create a review
Use the booking-scoped route. The project-level
POST /v1/projects/{projectId}/reviews
predates it and is deliberately permissive; it remains for existing integrations.
Reviews and the rating emails
After a booking ends MarketBox emails both sides asking for a rating, and follows up if none arrives. The client is asked to rate the supplier; the supplier is asked to rate the client and confirm they attended. The two arrive on the same cadence and are told apart byrole in the link.
A review linked to a booking stops the follow-ups for that side. The booking-scoped route
links it for you. A review posted through the project-level route without a bookingId does not,
and the recipient keeps being asked to rate something they have already rated.
The two directions suppress independently. A CLIENT_TO_SUPPLIER review stops the client’s
follow-ups only; the supplier keeps being asked until a SUPPLIER_TO_CLIENT review exists, and
vice versa. That is deliberate — one side answering says nothing about the other — so do not
expect writing one review to silence both.
Suppression keys on the review, not the attendance report. A supplier who confirms attendance
but leaves no rating will still be asked again.
Reporting on a booking
A report is a self-report. ACLIENT report says the client attended; a SUPPLIER report
says the supplier attended. Neither says anything about the other party, so a supplier cannot mark
a client as absent through this endpoint.
File a report
reportType defaults to ATTENDANCE, the only type today. reporterId is read off the booking
and is not accepted in the body.
Because this gets clicked from an email, resubmitting is safe:
note is not part of what a report asserts — the claim is reportType plus attended. Resending
those unchanged with different text returns 200 with the record as stored, original note
included. A filed report cannot be edited.
A report settles the booking, exactly as the same answer does in the MarketBox dashboard:
See Attendance and disputes.
A report can be filed only once the session has ended. Otherwise it’s
422 BOOKING_NOT_REPORTABLE, and nothing is written:
- before the session ends: “This booking cannot be reported on until its session has ended”
- on a
CANCELLEDbooking: “A cancelled booking cannot be reported on” - a
SUPPLIERreport on a booking that’s already settled: “This booking is already settled, so a supplier report can no longer change it”
status instead of an error.
GET /v1/projects/{projectId}/bookings/{bookingId}/reports returns both sides’ reports.
Averages
MarketBox maintains a running average as reviews are written, for suppliers and for clients:Supplier rating summary
200 OK
Reference
Endpoints
Review fields
Report fields
Errors
- Call MarketBox from your server — the API key must never reach a browser.
- Send
direction, stars and text only. Party ids come off the booking. - Read
subjectIdrather than deciding for yourself which party a rating is about. - Link reviews to the booking so MarketBox stops asking the client to rate it.
- Handle 409 as “already answered”, not as a failure — show what is on file.