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

A third purpose, identify_visitor, is in the list of purposes but is not offered yet, because nothing would call it.

Setting one up

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

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.

block_check answer

A JSON object with the result blocking. Other fields are ignored. A missing or mistyped result is a failure, never 'not blocking'.

Field Type Required Notes
blocking boolean yes
person_ref string or null no Optional: the person in the customer's own system. Limits: 1 to 256 characters.

block_check request

Asked when a booking is created: does this visitor already have a meeting that should block it? Signed like a webhook.

Field Type Always sent Notes
version number yes Values: 1 .
id string yes The request's id, equal to the webhook-id header. Limits: at least 1 character.
purpose string yes Values: block_check .
operation string yes Values: create , test .
account_id string yes Limits: at least 1 character.
timestamp string yes Limits: format date-time.
visitor object yes
visitor.email string or null yes
visitor.phone string or null yes
visitor.proven boolean yes The visitor arrived by a link that vouches for them.
visitor.external_ref string or null yes The vouching link's reference. Null unless proven is true.
event_type_id string or null yes Limits: at least 1 character.
start string yes The start of the booking being created. Limits: format date-time.

pick_owner answer

A JSON object with outcome: owner with owner_ref (a host id), or owner with owner_external (the owner's id in another system, mapped through the account's external ids) when owner_ref is absent, or no_owner. When owner_ref is present it decides and owner_external is not read. Other fields are ignored. Anything else is a failure, never 'no owner'.

Field Type Required Notes
(whole body) one of 3 shapes yes A JSON object with outcome: owner with owner_ref (a host id), or owner with owner_external (the owner's id in another system, mapped through the account's external ids) when owner_ref is absent, or no_owner. When owner_ref is present it decides and owner_external is not read. Other fields are ignored. Anything else is a failure, never 'no owner'.
{variant 1} object yes Shape 1 of 3, where outcome is owner.
{variant 1}.outcome string yes Values: owner .
{variant 1}.owner_ref string yes The owner, as a host's reference. Limits: 1 to 256 characters.
{variant 1}.person_ref string or null no Optional: the person in the customer's own system. Limits: 1 to 256 characters.
{variant 2} object yes Shape 2 of 3, where outcome is owner.
{variant 2}.outcome string yes Values: owner .
{variant 2}.owner_ref null no Absent or null: the owner is named by owner_external.
{variant 2}.owner_external object yes The owner as an id in another system.
{variant 2}.owner_external.system string yes The system's name, as the account's external ids name it: a lower-case letter, then lower-case letters, digits, _ or -, 1 to 32 characters. Limits: pattern ^[a-z][a-z0-9_-]{0,31}$.
{variant 2}.owner_external.external_id string yes The owner's id in that system, exactly as stored: 1 to 255 UTF-16 units on one line, no control character, no whitespace at either end. Compared with its case.
{variant 2}.person_ref string or null no Optional: the person in the customer's own system. Limits: 1 to 256 characters.
{variant 3} object yes Shape 3 of 3, where outcome is no_owner.
{variant 3}.outcome string yes Values: no_owner .
{variant 3}.person_ref string or null no Optional: the person in the customer's own system. Limits: 1 to 256 characters.

pick_owner request

Asked inside a routing form's submission: which host owns this visitor? Signed like a webhook.

Field Type Always sent Notes
version number yes Values: 1 .
id string yes The request's id, equal to the webhook-id header. Limits: at least 1 character.
purpose string yes Values: pick_owner .
operation string yes Values: route , test .
account_id string yes Limits: at least 1 character.
timestamp string yes Limits: format date-time.
visitor object yes
visitor.email string or null yes
visitor.phone string or null yes
visitor.proven boolean yes The visitor arrived by a link that vouches for them.
visitor.external_ref string or null yes The vouching link's reference. Null unless proven is true.
event_type_id string or null yes Limits: at least 1 character.
routing_form_id string or null yes Limits: at least 1 character.
rule_id string or null yes Limits: at least 1 character.
answers array of object yes Only the answers the routing rule names.
answers[] object yes
answers[].question_id string yes Limits: at least 1 character.
answers[].label string yes
answers[].answer string or array of string yes