Get a visit

Creates an expected visit: an invitation from a host when you use a secret key or OAuth token, or a pre-registration when you use a publishable key. Agoo links the visit to an existing visitor record when the phone number (or, without a phone, the email address) matches one, and creates a visitor record otherwise. - With `send_pass` (the default), Agoo sends the visitor a QR pass on the channels in `pass_channels`, trying them in order and falling back to the next if one fails. Leave `pass_channels` out to use your organisation's default order. Each message counts towards your SMS and WhatsApp allowance. - Fires `visit.created`, then `pass.sent` once the pass is sent. - The visitor is checked against your watchlist straight away. On a match the visit is held for security (`awaiting_approval`): no pass is sent, no host is asked, `watchlist.matched` fires and your security team is alerted. The response shows only the status. - `type` is one of your organisation's visit type keys (see `GET /visit-types`) and defaults to `meeting`. A key your organisation doesn't have, or a type that is turned off, returns `validation_failed`. - `custom_fields` are checked against the visit form for the visit's `type` (see `GET /forms`). - Pre-registrations made with a publishable key have `source: pre_registration`. If the site requires host approval for pre-registrations, the visit starts as `awaiting_approval`, the host is asked, and the pass is sent once the host approves (the visit is then `expected` again). - Each visitor new this month counts towards your plan's visitors a month. A new visitor beyond it returns `plan_required`; visitors already counted this month can always be invited again. - An unknown `site_id`, or a `host_id` that isn't an active person who can host, returns `validation_failed`. - With a publishable key, `type` must be open for pre-registration (`pre_registration: true` in `GET /visit-types`); any other type, including the default `meeting` when it isn't open, returns `validation_failed` at `body.type`. `custom_fields` may contain only the fields in that type's `public_form`; a field your staff fill in returns `validation_failed` at `body.custom_fields.<key>`. Publishable keys can't list or search people, so your page must already know the `host_id`; to let visitors search for their host, use the hosted pre-registration page (the embed script). - In test mode, messages go to the console's test outbox instead of the visitor. **Scope:** `visits:write` · **Plan:** Pro and Enterprise in live mode; every plan in test mode. **Publishable keys:** allowed, for visit types open for pre-registration.