Skip to main content
This page is part of Build a supplier portal. Paths are relative to /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

  1. GET /demand?area=zone&days=30. area is zone (the default) or wider, the zone plus a 15-minute drive. days is 30 (the default), 90 or 180. state is ok, not_enough_data (fewer than 20 bookings, and no grid) or no_area. Each grid covers 06:00 to 22:00 local, in the zone named by window.zone: 7 rows, where day index 0 is Monday, by 16 hourly columns, where index 0 is 06:00.
  2. To hide a suggestion, POST /demand/suggestions/{key}/dismiss with its key from the response — for example open:WED:14:00-16:00. DELETE the same path to show it again. Both are idempotent.
  3. GET /search-insights?days=28. days is 7, 28 (the default) or 90. For a custom range, send from and to (YYYY-MM-DD, at most 365 days) instead. state is ok, or nothing_yet when no counted search involved the supplier in this window or the one before. A nothing_yet response has no tiles, missed searches or breakdowns: show an empty state, not zeros.
The business switches each insight on per project. While a switch is off, its routes answer:
Search insights count only searches your site reported as drawn. See Report site events.

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:
  1. Poll GET /alerts/summary for the badge, no more often than every 60 seconds. The badge is unreadCount plus one for each entry in conditions. When unreadCapped is true there are 100 or more unread: show “99+”. The response is Cache-Control: no-store.
  2. When the supplier opens the panel, call GET /alerts?filter=unread, or filter=all (the default). A page holds up to limit alerts (1–100, default 20). Follow nextCursor until it is null.
  3. When the supplier opens an alert, POST /alerts/{alertId}/read. It answers 204, also when the alert was already read. An id that isn’t in this supplier’s inbox is a 404, the same answer as an id that doesn’t exist.
  4. For “Mark all as read”, POST /alerts/read-all. It answers { "data": { "updated": 12, "more": false } }. Call it again while more is true.
A cursor is valid only for the filter that produced it. Any other cursor is refused, so start again from the first page:
Alerts hold no URL. Each carries a 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.