Search verified guides, send a job, and get a named guide back — without leaving
your itinerary tool. Authentication is a bearer key we issue you; writes require
an Idempotency-Key so a retry can never book twice.
Area ids, timezones, and whether each jurisdiction licenses guides at all.
Search by area, dates, language and speciality. One price, already inclusive.
Name a guide, or put the job to everyone who matches.
Poll for the outcome. The confirmed guide's phone and email are on
GET /v1/assignments/{id}.
Choose from the guides who applied to a standard broadcast.
The group, the pickup point and the time. Sent whole each time, not as a diff — we store what you last sent.
Exactly what your guide is shown, so you can check it rather than hope.
Register an endpoint and we POST to it when a guide accepts, declines, applies to a broadcast, when a booking is cancelled or completed, when a request expires, and when a manifest changes. HTTPS on the standard port, a public address, and no redirects — we refuse private and internal hosts outright.
Every call carries HeyGuides-Signature: v1,t=<seconds>,s=<hmac>.
Verify it by computing HMAC-SHA256 of <t>.<raw request body>
with your signing secret and comparing in constant time — then reject anything whose
t is more than a few minutes old, so a captured call cannot be replayed
at you tomorrow. The secret is shown once when you register the endpoint; we derive
it rather than store it, so we cannot show it to you again and a breach of ours
cannot forge it.
Delivery is at-least-once and retried for about nine hours.
Dedupe on HeyGuides-Event-Id — the same event may
arrive twice, and arrives once per endpoint you have registered. Payloads carry ids
and counts, never traveller names; fetch the detail from the manifest endpoints when
you need it. An endpoint that refuses twenty deliveries in a row is switched off and
we tell you on your account page.
notes on a request is shown to every guide you invite,
before any of them accepts — a broadcast reaches up to 25 people. Put anything
about the group in manifest.notes instead, which only the guide who
takes the job ever sees. It is the same word twice and the difference matters.
Names and nationalities are disclosed to the one guide holding the booking and to nobody else — not to the others you asked, not to a guide whose booking you cancelled. They are deleted 30 days after the tour, along with your manifest notes; the pickup point and the counts stay. Send a roster after that window and we refuse it rather than store it again.
Three things to know before you build: tour dates are calendar days in the area's
own timezone, never timestamps; pickup.time is a civil
HH:MM read in that same timezone; and
availability: "unknown" means we know of no conflict,
not that the guide is free.