Skip to main content
MarketBox records two kinds of feedback about a booking:
  • 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”.
Both hang off a booking, so this page builds on Bookings. If you are building your own page for clients and suppliers to leave feedback, everything you need is here. For a walkthrough, from checking who may review to a supplier’s rating badge, see Collect reviews and show ratings.

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 — SUPPLIER or CLIENT
  • subjectId — the id of whoever is being rated
A rating only ever moves the subject’s average. Reviews written before two-way reviews existed carry no 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. Set reviewRedirectUrl 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.
Three more tokens, {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.
Responses carry 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 409 REVIEW_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 by role 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. A CLIENT 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 CANCELLED booking: “A cancelled booking cannot be reported on”
  • a SUPPLIER report on a booking that’s already settled: “This booking is already settled, so a supplier report can no longer change it”
A supplier who clicks an old email after an operator settled the booking gets that last one. Show them the booking’s current 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
A subject nobody has rated returns zeros rather than a 404. Use these instead of paging every review to compute a star rating yourself.

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 subjectId rather 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.