List visits

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`). A photo or file question takes the ID of a file you registered first (`POST /files` with `kind` `answer_photo` or `answer_file`); the file then belongs to the visit and is deleted with it. A signature takes its strokes, `[[[x, y], …], …]` in a 1000 × 400 box. An ID scan takes any of `document_type`, `number` and `image` (an `id_image` file): the answer keeps `last4` (the number's last four characters), the full number is kept encrypted on the visitor and never returned by the API, and the visitor can be matched against your watchlist by it. - 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.