Guides

Visitors

Use the API to pre-register visitors, change or cancel their visit, and record when they arrive and leave. These endpoints are part of ArrivalsHQ, which also covers staff sign-in, deliveries and the evacuation roll call.

Pre-registering a visitor

Send a POST request to /visitors.

The required fields are name, user_id (the host, the person being visited) and notify_employee, plus an office:

  • office_id: the office being visited. On ArrivalsHQ plans, the office must be on a site.
  • site_id: on ArrivalsHQ plans, send this instead to use the site's default office, or as well as office_id to check the office is on that site.

company and expected_arrival are needed in most cases too:

  • company: required unless your organisation's visitor rules make it optional.
  • expected_arrival: required unless you send time_in for a visitor who has already arrived, or dates for a repeat visitor. Send it in the office's local time.
  • Other fields: email, car_registration_number and locale are required only if your visitor rules say so.
Request body
{
  "name": "Jamie Fictional",
  "company": "Example Ltd",
  "email": "jamie@example.com",
  "user_id": "9c1d2e3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f",
  "office_id": "5e4d3c2b-1a09-4f8e-a7d6-c5b4a3928170",
  "expected_arrival": "2026-11-12 10:00",
  "notify_employee": true
}

Invitations and notifications

The visitor is emailed an invitation with their sign-in code if all three of these are true:

  • welcome emails are switched on in your visitor rules
  • the visitor has an email address
  • you didn't send send_invite: false

When notify_employee is true, the host is emailed the visit's details.

Bookings, documents and visitor types

ArrivalsHQ plans can do more when you register a visitor:

  • bookings: books a desk, parking space or meeting room for the visit. Use "auto" as the ID to let Clearooms pick one. If a booking can't be made, nothing is created and the call returns 422.
  • nda_document_ids: sends documents for the visitor to read and sign in advance.
  • accessibility_notes: lets reception know what the visitor needs.
  • visitor_type_id: sets the visitor type, as set up in the portal.
With a meeting room for the visit
{
  "name": "Jamie Fictional",
  "company": "Example Ltd",
  "email": "jamie@example.com",
  "user_id": "9c1d2e3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f",
  "office_id": "5e4d3c2b-1a09-4f8e-a7d6-c5b4a3928170",
  "expected_arrival": "2026-11-12 10:00",
  "notify_employee": true,
  "bookings": {
    "room": { "room_id": "auto", "start_time": "10:00", "end_time": "11:00" }
  }
}

Changing or cancelling a visit

To move a visit that hasn't started, send only what changes to PATCH /visitors/{visitorId}/visit. You can change user_id, office_id, expected_arrival and visitor_type_id:

Request body
{
  "expected_arrival": "2026-11-12 10:30"
}

The visit's desk, parking space and meeting room move with it. If any of them can't, nothing changes, and the call returns 422 with code set to booking_clash and a list of the clashes. A new date, office or host re-sends the visitor's invitation and emails the hosts involved.

To cancel a visit that hasn't started, call POST /visitors/{visitorId}/cancel. Its bookings are released, and the visitor and host are emailed if they would normally hear about the visit. The visit is kept, with status set to cancelled.

To change contact details, use PUT /visitors/{visitorId}. Fields you leave out keep their current value.

Signing a visitor in and out

To sign a visitor in at the current time, call POST /visitors/{visitorId}/sign-in with no body. The host is notified and the visitor appears on the evacuation roll call, just as when they sign in at the kiosk.

To sign them out, call POST /visitors/{visitorId}/check-out. Send no body to use the current time, or send time_out to set it yourself:

Request body
{
  "time_out": "2026-11-12 16:45"
}

You can also set time_in and time_out directly with PUT /visitors/{visitorId}, for example to correct a record. The sign-in endpoint is better for a live arrival, because it also runs the notifications.