- keep their profile and photo up to date;
- see their bookings and file attendance reports;
- cancel or move a booking, when the service allows it;
- set their working hours, blocked time, travel zones and venues;
- read their demand and search insights;
- see and clear their alerts: new, moved and cancelled bookings.
me is the supplier the user token belongs to. The API never reads a supplier
id from the path or the body. A booking, schedule, blocked time or travel zone
id that isn’t theirs is a 404 — the same answer as an id that doesn’t exist.
The dashboard and your portal run the same code. Every supplier-plane route
is the twin of a dashboard route, with the same rules. A supplier gets the same
answer, and the same refusal, from both.
The pages of this guide
Three task guides go deeper on the same plane:
- Supplier day view and attendance reports:
the agenda’s window and
expandrules,viewerActions, every report outcome, and overdue reports. - Weekly hours, exceptions and seasons:
how
rruleis read, holidays and time off, seasonal schedules, a timezone move, and checking the result. - Set up a mobile supplier’s service area: a travel zone and the hours in it, in order, and how to check a client’s address is covered.
First sign-in: set the supplier up
A supplier who signs in for the first time may have no hours yet. Set them up in this order. The/suppliers/me calls take the API key and the supplier’s
access token. The service list and the availability check take the API key
alone.
1
Check access
GET /suppliers/me/access answers 200 with allowed and a reasonCode.
Go on only when allowed is true; otherwise show its message. See
Check access first.2
Read the profile
GET /suppliers/me returns the supplier’s own profile, including timezone
and serviceIds. See
Edit the profile.3
Set the timezone
PATCH /suppliers/me with timezone. Hours and blocked time take the
profile zone when you omit timezone on create. When neither the profile nor
the project has a zone, the create is a 400 BAD_REQUEST. See Times.4
Set the services
PATCH /suppliers/me with serviceIds, taken from
GET /v1/projects/{projectId}/services?status=LIVE. A schedule’s
serviceOfferingIds must be ACTIVE offerings of these services. You can
send timezone and serviceIds in one PATCH.5
Choose where they work
For in-home work, create the supplier’s own travel zone with
POST /suppliers/me/travel-zones. See
Set up a mobile supplier’s service area.
For a venue, pick one from GET /suppliers/me/locations. See
Venues.6
Create the schedule
POST /suppliers/me/schedules with the hours, naming the zone in
travelZoneRef or the venue in locationRefs. A travel zone on its own
makes no one bookable. See
Set working hours.
If the project uses start and end of day locations, the schedule can also
carry where the supplier’s day starts and ends. See
Start and end of day locations.7
Check what clients are offered
POST /v1/projects/{projectId}/availability/suppliers takes the API key
alone, so your server can run it after the supplier saves. Find the supplier
by supplier.supplierId and read their open days. Search updates shortly
after a schedule is saved, so allow a short delay. See
Check the result.Times
- A booking’s time is an instant plus a zone.
bookingStartUtcandbookingEndUtcare UTC instants.bookingTzis the booking’s home zone, andbookingLocalDate,bookingLocalStartTimeandbookingLocalEndTimeare the same times in that zone. Show the booking in its home zone, labelled. - A reschedule carries one UTC instant, the new
startTime. The booking keeps its length, and its local times are worked out again in its own zone. - Hours and blocked time are wall-clock rules:
HH:MMtimes andYYYY-MM-DDdates in the row’stimezone, with a weeklyrrule. Omittimezoneon create to use the supplier’s profile zone, or the project’s default zone when the profile has none. When neither exists, the create is a400 BAD_REQUEST. An update keeps the row’s stored zone. - Insights are given in the supplier’s home zone.
- Query windows on bookings (
startDate,endDate) are UTC instants.
Not on the supplier plane yet
These dashboard features have no supplier-plane route yet. Suppliers use the dashboard for them:- Google Calendar — connecting a supplier’s calendar.
- Invitations — inviting a supplier into the project. A supplier accepts once in the dashboard, then signs in to your portal with the same account.
Reference
Endpoints used in this guide
Every route on the supplier plane takes the API key and the supplier’s access token.
Key-only routes the portal also uses, with the API key alone: