/v1/projects/{projectId}/suppliers/me. Every call
takes your API key and the supplier’s access token. See
Sign-in and access.
Demand and search insights
GET /demand?area=zone&days=30.areaiszone(the default) orwider, the zone plus a 15-minute drive.daysis30(the default),90or180.stateisok,not_enough_data(fewer than 20 bookings, and no grid) orno_area. Each grid covers 06:00 to 22:00 local, in the zone named bywindow.zone: 7 rows, where day index 0 is Monday, by 16 hourly columns, where index 0 is 06:00.- To hide a suggestion,
POST /demand/suggestions/{key}/dismisswith itskeyfrom the response — for exampleopen:WED:14:00-16:00.DELETEthe same path to show it again. Both are idempotent. GET /search-insights?days=28.daysis7,28(the default) or90. For a custom range, sendfromandto(YYYY-MM-DD, at most 365 days) instead.stateisok, ornothing_yetwhen no counted search involved the supplier in this window or the one before. Anothing_yetresponse has no tiles, missed searches or breakdowns: show an empty state, not zeros.
Alerts
These are the bell in the MarketBox dashboard: the same alerts, from the same
inbox. Marking one read in your portal clears it in the dashboard too, and the
reverse. The portal always reads the supplier’s own supplier inbox. Staff
and client alerts never appear here, whatever other roles the person holds.
To build a bell:
- Poll
GET /alerts/summaryfor the badge, no more often than every 60 seconds. The badge isunreadCountplus one for each entry inconditions. WhenunreadCappedistruethere are 100 or more unread: show “99+”. The response isCache-Control: no-store. - When the supplier opens the panel, call
GET /alerts?filter=unread, orfilter=all(the default). A page holds up tolimitalerts (1–100, default 20). FollownextCursoruntil it isnull. - When the supplier opens an alert,
POST /alerts/{alertId}/read. It answers204, also when the alert was already read. An id that isn’t in this supplier’s inbox is a404, the same answer as an id that doesn’t exist. - For “Mark all as read”,
POST /alerts/read-all. It answers{ "data": { "updated": 12, "more": false } }. Call it again whilemoreistrue.
filter that produced it. Any other cursor is
refused, so start again from the first page:
target, which your portal maps to its
own page. The LESSON_ kind names are fixed identifiers; each is about a
booking.
The
kind and target.kind enums also list client and staff values, which a
supplier inbox doesn’t receive. Skip any kind or target your portal doesn’t
map, rather than failing on it.
For example, PAYMENT_NEEDS_REVIEW is a staff alert. It goes to the
project’s admins, never to a supplier inbox. It flags money Stripe has
already moved that needs a person to look at it. Its target is
{ "kind": "order", "orderId" }, and payload.paymentReason says why:
A supplier portal never receives this alert. If you validate responses
against strict enums generated from the reference, they now include these
values.
The
payload holds what the copy needs: clientName (shown as the service’s
participant settings allow, for example “Jordan L.”), serviceName, and the
booking’s start as startUtc with its zone. Show the time in that zone. See
Times.
Conditions are not alerts. A condition such as MY_REPORTS_OVERDUE is
computed on every read. It has no read state, and “Mark all as read” doesn’t
clear it. It leaves when the supplier files the reports, and its count can take
up to 5 minutes to catch up. Alerts are kept for 90 days.