Lookups
Availies does not know your customer records, so when a step needs to know who a visitor is, it asks. An account registers one address for each question, and Availies calls it with a signed request and reads a short answer.
What can be asked
-
block_checkis asked when a booking is created: does this visitor already have a meeting that should block it? -
pick_owneris asked inside a routing form's submission: which host owns this visitor?
A third purpose, identify_visitor, is in the list of purposes but is not offered yet,
because nothing would call it.
Setting one up
-
createLookupEndpoint adds an endpoint and
answers its signing secret once. The address must be
httpson a public host and is checked exactly as a webhook endpoint's address is. - testLookupEndpoint calls the endpoint now with synthetic input, signed and timed like a real lookup, and shows the parsed answer or why it failed. Nothing is stored or counted.
- rotateLookupSecret replaces the secret.
The request
A POST with a JSON body, signed the same way as a webhook: the webhook-id,
webhook-timestamp and webhook-signature headers, made with the endpoint's
own secret. See webhooks for how to check them. A retry keeps the
same webhook-id and body, with a fresh timestamp and signature.
Time and failure
-
Each endpoint has a time budget,
timeout_ms, from 100 to 10000 milliseconds, 2000 by default. It covers the whole step: the address check, the call, one retry and reading the answer. A slow answer is a missing answer. -
Each endpoint also says what a failure means, with
on_failure. Withfail_closedthe visitor is asked to try again and nothing is stored. Withfail_openthe step goes on as if nothing was found, and the failure raises an alert. A failed check never permits what another check refuses. A new endpoint starts withfail_closedforpick_ownerandfail_openforblock_check. - A missing or mistyped result in the answer is a failure, never "nothing found". Fields you add to the answer are ignored. An answer larger than 16 KB fails.
A lookup is advisory
Two requests can both hear "not blocking" before either is committed, because Availies cannot hold a lock in your system. A lookup is a best-effort guard. What Availies itself guarantees is its own rule about a visitor's other bookings, which is counted in the same statement that admits a booking. If you need exclusion, enforce it in your own system too.
Naming an owner
A pick_owner answer names the owner by owner_ref, a host id. Only when
owner_ref is absent or null does it name the owner by
owner_external, an id in another system, which Availies maps through the account's
external ids in the same step. Set a host's id in another system with
setHostExternalId. An id that is not mapped, or a
mapped host who is not one of the rule's hosts, is a failure, handled as the endpoint's
on_failure says.