Create a new visit with guests and hosts.

Creating a visit is a three-step process: look up the available visit types, optionally fetch the custom field schema, then submit the visit.

Step 1 — Fetch visit types

Call GET /v1.0/visits/visit-types with your location_id to get the list of active visit types. Each type has an id and a human-readable name (e.g. "Interview", "Contractor").

Use the id from this response as the type_id field when creating or updating a visit. If the location has no custom visit types configured, the list will be empty and you can omit type_id.

GET /v1.0/visits/visit-types?location_id=<location_id>

Step 2 — Fetch the custom field schema (if applicable)

Call GET /v1.0/visits/custom-visit-forms with your location_id. The response describes every custom field that must or can be supplied when creating a visit:

• guest_fields — collected per guest (e.g. "Company name", "Vehicle plate")
• visit_fields — collected once for the entire visit (e.g. "Purpose of visit")

Each field has a type (SHORT_TEXT, LONG_TEXT, or SINGLE_SELECT), an id, a label, and a required flag. For SINGLE_SELECT fields, the allowed values are listed under choices.

If data is null, the location has no custom form and you can skip the custom_fields arrays entirely.

GET /v1.0/visits/custom-visit-forms?location_id=<location_id>

Step 3 — Create the visit

Call POST /v1.0/visits with the data collected above.

{
  "location_id": "<location_id>",
  "start": "2025-06-01T09:00:00-05:00",
  "type_id": "<id from Step 1>",
  "hosts": [{ "user_id": "<robin-user-id>", "is_visible_to_guests": true, "send_notifications": true }],
  "guests": [
    {
      "guest_name": "Jane Smith",
      "guest_email": "[email protected]",
      "custom_fields": [
        { "id": "<field-id from Step 2>", "value": "Acme Corp" }
      ]
    }
  ],
  "custom_fields": [
    { "id": "<visit-field-id from Step 2>", "value": "Sales meeting" }
  ]
}

Guest-level custom_fields go inside each guest object. Visit-level custom_fields go at the top level of the request body.