<!-- https://unlockos.io/manual/forms -->

# Form Management Help

## Overview

Form Management lets you create and manage all information-collection forms for your facility in one place. From guest check-in forms (a superset of the legacy Guest Form) to member registration, surveys, and facility inspections — you can run multiple forms per facility, each tailored to its use case.

What you can do on this page:

- View and filter all forms for a facility
- Create a new form (name, description, target scope, public URL slug)
- Click any form to open the form editor (fields and bindings)
- Manage form status (Draft / Active / Archived)

---

## How to Access

Main menu → select "Forms".

---

## Features

## Feature 1: Form List and Filtering

All forms appear as cards showing the form name, scope badge, status badge, public slug (if set), and last updated date.

### Scope Filter

Use the dropdown to narrow the list to a specific scope.

| Scope | Use Case |
|-------|----------|
| Reservation | Guest information collected at check-in or booking |
| Identity | Personal information for member registration or renewal |
| Space | Inspection or report forms for rooms and equipment |
| Facility | Facility-wide configuration or application forms |
| Standalone | Survey or contact forms published via a public URL |

---

## Feature 2: Creating a New Form

Click "New Form" to expand an inline creation form.

### Input Fields

| Field | Description | Required |
|-------|-------------|----------|
| Form Name | Display name in the admin panel (e.g., Check-in Guest Form) | Yes |
| Memo (internal) | Internal note on the form's purpose, shown only in the admin panel (never to guests) | No |
| Target Scope | Select from the 5 scopes above | Yes |
| Public URL Slug | Shown only when Standalone is selected. Use lowercase letters, numbers, and hyphens (e.g., customer-survey-2026) | Optional for standalone |

> There is no field for the guest-facing description (see "Description for guests" below) on this creation screen. Open the form after creating it to set that.

### Steps

1. Click "New Form"
2. Enter a form name
3. Optionally enter a description
4. Select the target scope
5. For standalone, enter a public URL slug
6. Click "Create"
7. You are automatically taken to the form editor

---

## Feature 3: Form Editor

Click any form card in the list to open the form editor. The editor has three sections.

### 3-1: Form Metadata

| Field | Description |
|-------|-------------|
| Form Name | Display name in admin |
| Description for guests | Text shown to the guest at the top of the form (see below) |
| Memo (internal) | Internal note, shown only in the admin panel (never to guests) |
| Status | Draft / Active / Archived |
| Target Scope | 5 scopes to choose from |
| Public URL Slug | Standalone only. Accessed at /form-demo?facility=…&slug=… |
| Reuse Policy | Controls pre-fill behavior (see below) |
| Reuse Scope | UnlockPass-wide / Organization / This Facility only |

Click "Save" to confirm changes. Click "Delete" to remove the form (a confirmation dialog appears). System default forms ("Default Reservation Form", etc.) cannot be deleted.

#### Description for guests

"Description for guests" is text shown directly to the guest, right before the form's input fields (up to 500 characters, with a live character count). Leave it blank and nothing is shown (matching the previous look of the form).

- This is a separate field from "Memo (internal)". **The memo is never shown to guests** — it's for the admin to note what the form is for
- A typical use: "We collect this information as required by the Hotel Business Act," explaining to the guest why the information is being requested
- If saving fails (for example, while a server update is still rolling out) an error message reports it. Since the screen can still look normal, check the saved state after saving

#### A form is never asked twice within the same reservation

When a form is bound to a plan, the guest fills it in **at booking time**. If an answer is already recorded for that reservation, **the form is not shown again at check-in for that same reservation**. Booking and check-in are consecutive steps of the same stay, so — regardless of the reuse policy below (Every Visit / One-Time / Periodic) — the same guest is never asked to fill the form twice within one reservation.

> **Walk-in (direct check-in) or reservations where the form was not filled at booking** still show the form at check-in, as before.

#### Reuse Policy (UnlockPass Pre-fill)

The reuse policy controls how a form is treated across **separate reservations and future stays** (the same-reservation no-repeat behavior above always applies, independent of this setting). When a guest has submitted this form on a previous reservation, their previous answers can be pre-filled on the next submission.

| Policy | Behavior | Typical Use Case |
|--------|----------|-----------------|
| Every Visit (per_visit) | Guest re-enters all fields on **each new reservation**. No pre-fill when scope is "This Facility only" | Legally required guest registries (e.g. Japanese ryokan law) |
| One-Time (one_time) | After the first submission, later reservations show a read-only preview (no edits allowed) | Initial membership registration |
| Periodic | Re-entry required on reservations after N days | Annual or periodic facility-use agreements |

Setting the reuse scope to "UnlockPass-wide" allows answers submitted at other facilities to be used as pre-fill.

**Guest-facing Confirm step:**

When previous answers are available, the guest sees a read-only preview of their last submission with two buttons:

- "Submit as-is" — submits without changes
- "Edit" — returns to the input form to make changes (hidden for `one_time` policy)

### 3-2: Form Fields

All fields in the form are shown in a table.

**Reservation-scope forms include the following 11 default fields (cannot be deleted):**

| # | Field Name | Type | Initial State | Required | Display Condition |
|---|------------|------|---------------|----------|-------------------|
| 1 | Full Name | Text | Enabled | Required | Always |
| 2 | Date of Birth | Date | **Disabled** | Optional | Always |
| 3 | Mobile Number | Phone | Enabled | Required | Always |
| 4 | Address | Text | Enabled | Required | Always |
| 5 | State / Province | Text | **Disabled** | Optional | Always |
| 6 | Postal Code | Text | **Disabled** | Optional | Always |
| 7 | Nationality | Select | Enabled | Required | Always |
| 8 | Passport Number | Text | Enabled | Required | When nationality is not the host country |
| 9 | Passport Photo | Image | Enabled | Required | When nationality is not the host country |
| 10 | ID Number | Text | Enabled | Required | When nationality is the host country |
| 11 | ID Document Photo | Image | Enabled | Required | When nationality is the host country |

> **"Contact" has been renamed to "Mobile Number"** (previously renamed once already, from "Phone Number"). The underlying `field_key` remains `contact` for backward compatibility. The type has also been changed to the phone number type so it can support SMS verification — see [SMS Phone Verification](sms-verification.md) for details.

> **Fields with an initial state of "Disabled"** (Date of Birth, State / Province, Postal Code) appear grayed out with a "Disabled" badge in the list. They can be enabled with a single tap. The Required toggle becomes available after enabling.

> **A newly created form starts with only "Full Name" enabled**, unlike the table above — the other 10 fields all start disabled. Since UnlockOS is used across many business types beyond accommodation (coworking, lockers, parking, and more), starting with address, nationality, passport photo, and ID document photo all enabled would mean facilities outside the hospitality space have to switch 7 fields off before they can begin. The table above shows how the **not-yet-saved** default fields of an existing form appear in the list; enable whichever fields you need with the "Enabled" toggle.

**Other scopes have no default fields — add any custom fields you need.**

#### Enabling and Disabling Default Fields

All default fields can be toggled on or off individually.

- Disabled fields are not shown to guests on the input form
- In the field list, disabled fields appear grayed out with a "Disabled" badge
- To enable a field, turn on its "Enabled" toggle (auto-saved immediately)
- The Required toggle can only be changed while the field is enabled
- Example: facilities that only host domestic guests can disable all nationality and passport fields

#### Disabling a field that other fields depend on

Some fields (like Passport Number and Passport Photo) reference another field through their display condition (e.g., shown only when nationality is not the host country). The row for the referenced field (e.g., Nationality) always shows which fields reference it.

If you try to disable a field that other fields depend on, you're asked whether to disable it together with the fields that reference it.

- The confirmation dialog lists every field that will be disabled
- Choosing "Disable" disables the dependent fields first (the parent is never left disabled with an enabled child, since that is the exact condition that causes display-condition evaluation to misbehave)
- Disabled fields can always be re-enabled individually afterward
- If only some fields fail to save, the dialog reports which ones and why
- If a built-in system field (one whose type or required status can't be changed) is among the dependents, it cannot be disabled and the dialog explains why

#### Reordering Fields

You can change the order in which fields appear on the form. Changes are saved immediately.

- **Desktop**: Drag the `⋮⋮` handle at the left of each row to a new position. The drop target is highlighted in the brand color
- **Mobile**: Use the `↑` / `↓` buttons on each card to move a field one position at a time
- Custom fields and default fields can be freely mixed in any order

#### Adding a Custom Field

| Input | Description | Required |
|-------|-------------|----------|
| Label (Japanese) | Japanese label shown to users | Yes |
| Label (English) | English label shown to users | No (falls back to Japanese) |
| Field ID | Internal system identifier | No (auto-generated, see below) |
| Field Type | text / number / tel (phone number) / email / textarea / select / date / image / checkbox (consent) | Yes |

Newly added custom fields are optional by default. Toggle "Required" to make them mandatory.

#### Auto-generated field IDs

Leave the field ID blank and it is derived automatically from the **English label** (falling back to the Japanese label if the English one is empty, and finally to a number like `field_1` if neither can be used). A hint under the input shows exactly what will be assigned before you submit.

- If the derived ID would collide with one already in use, it is shifted automatically — you won't accidentally overwrite an existing field
- If you type an ID yourself, it is used as-is (typing an existing field's ID intentionally overwrites that field)
- Once assigned, a field ID never changes when you edit the label later (other features may reference a field by its ID)

#### Consent (checkbox)

Selecting **Checkbox (consent)** as the field type adds a consent-style checkbox, such as "☑ This plan is women-only. Please proceed only if you agree." Use it to collect agreement to a condition rather than to collect an attribute like gender.

- An unchecked box counts as "not filled in." **If the field is marked required, the guest cannot submit without checking it**
- **A required checkbox always asks the guest to check it again**, regardless of the reuse policy (Every Visit / One-Time / Periodic). Carrying a previous consent forward and letting the guest skip past the confirmation screen would undermine the point of recording "this guest was shown the condition and agreed to it on this reservation"
- An optional (non-required) checkbox behaves like an ordinary Yes/No question and follows the reuse policy like any other field
- In the admin panel (reservation detail, member detail response views), a checked box shows as "Agreed" and an unchecked one as "Not agreed"

#### Configuring choices (dropdown)

Selecting **select** as the field type reveals a choices editor underneath. Whatever you enter there is what the guest sees in the dropdown.

| Input | Description |
|-------|-------------|
| Label (Japanese) | Japanese wording shown in the dropdown |
| Label (English) | Wording used in English. Falls back to the Japanese wording |
| Stored value | The value saved as the answer and exported to CSV. Falls back to the Japanese wording |

- Use "+ Add choice" to add a row, `↑` / `↓` to reorder, `×` to remove. The dropdown follows this order
- **A select cannot be saved with zero choices.** An empty dropdown gives the guest nothing to pick, and a required one makes the whole form unsubmittable
- Two choices cannot share a stored value — the stored value *is* the answer, so duplicates are indistinguishable afterwards

To edit the choices of an existing field, click the "N choices" badge in the Type column of the field list; the same editor opens under that row. A field with no choices yet is flagged in red as "No choices", so a missing setup is visible at a glance.

Changing a stored value later does **not** rewrite answers already submitted — they keep the old value. To fix wording only, edit "Label (Japanese)" and leave the stored value alone.

#### SMS Verification (phone field confirmation)

Any phone-type row (the default "Mobile Number" field, or a custom field you create with the phone number type) shows an "SMS Verification" badge (toggle) next to the field name. Turning it ON means the guest must confirm that phone number with an SMS code before they can submit the form — whether the form is shown at booking time or at check-in time.

This toggle can only be operated on a row that meets both conditions:

- The field is marked "Required" (an optional field could be submitted blank, making verification meaningless)
- The facility has already configured an SMS sending source (if not, a banner and link appear above the field list)

See [SMS Phone Verification](sms-verification.md) for how this works end to end.

#### Default Pending Reservation Form

The pending reservation form — used when a plan requires manual approval before confirmation — is a slimmed-down version of the standard reservation form. It includes the following **8 fields** and excludes the international identity fields:

```
Full Name / Date of Birth / Phone Number / Address / State & Province / Postal Code / ID Number / ID Document Photo
```

(Nationality, Passport Number, and Passport Photo are not included.)

Enabling/disabling, required toggling, and reordering work the same way as the standard form.

#### Auto-save

The following actions are saved to the server immediately — no "Save" button needed:

- Toggling a field on or off
- Toggling the Required setting
- Reordering fields (drag-and-drop or ↑↓ buttons)
- Adding or deleting a custom field

The "Save" button is only required for **form metadata** (name, description, status, scope, reuse policy, etc.).

### 3-3: Bindings

Bindings specify where a form is displayed.

| Type | Description | When the form appears |
|------|-------------|----------------------|
| Plan | Attached to a specific pricing plan. Guests who book that plan see this form | Follows the form's own display-timing setting (at booking = Booking / Go app just before payment, at check-in, or both) |
| Event | Attached to a specific event | At event sign-up |
| Standalone URL | Published as a public-access standalone form | On direct URL access (no login required) |

To add a binding, select the type, enter the plan or event UUID (if applicable), and click "Add".

### How the form is chosen

Form attachment points are spread across four screens. Which one actually applies is decided by **where the reservation came from** — exactly one match — falling back to the default check-in configuration when nothing is attached there.

| Order | If the reservation… | Binding used | Where you set it |
|---|---|---|---|
| 1 | came from an external PMS integration | the integration connection's form | Reservation Management > Check-in (integration row) |
| 2 | came from an iCal import (no plan) | the iCal feed's form | Reservation Management > Check-in (iCal row) |
| 3 | came from a Google Calendar import (no plan) | the calendar's form | Reservation Management > Check-in (calendar row) |
| 4 | was created in Reservation Management > Check-in | that check-in configuration's form | Reservation Management > Check-in (default configuration) |
| 5 | was booked by a guest who chose a plan | the plan's form | "Forms applied" in the plan editor |
| — | has nothing attached above | **the default check-in configuration's form** | Reservation Management > Check-in (default configuration) |

The first matching row wins — bindings never stack. This is why non-default check-in configurations have no form picker: those reservations use the default configuration's form.

> **The fallback to the default has one exception.** When a guest checks in from their own reservation while signed in to the Booking / Go app, a **plan-booked** reservation does not fall back to the default check-in configuration's form (by design: that guest sees only the form for the plan they chose). Host check-in URLs, kiosks, and integration/import reservations still fall back as usual.

> **When the form appears is decided by the form itself.** A plan-bound form whose display timing is "at check-in" or "both" also appears at check-in. "At booking only" means it will not.
>
> Within one reservation, a form already answered at booking is never shown again at check-in, regardless of the reuse policy.

> **Plan binding vs. default check-in configuration form:**
> - **Plan binding** → shown to guests who booked that plan. Whether it appears at booking, at check-in, or both is decided by the **form's own display-timing setting**.
> - **Default check-in configuration form** → the form is shown to guests **at check-in time** via a host-shared check-in URL or kiosk.
>
> A guest booking through the Booking app and checking in themselves will see only the plan-bound form (at booking). A guest who uses your check-in URL or kiosk will see the default check-in configuration form (at check-in). See [Check-in Configuration help](checkin-config-form.md) for the full path breakdown.

### 3-4: Guest-facing Preview

The "Preview" button at the top of the "3-2: Form Fields" list shows **exactly what the guest will see**, without leaving the editor.

- Only fields that are "Enabled" in the list **and already saved** to the database are shown. A field you just toggled but haven't saved yet is called out with a note that it doesn't reach guests yet
- Display conditions (e.g. the passport field only appearing for a non-host-country nationality) and whether the Submit button is disabled by required fields are evaluated exactly as they are for a real guest
- Submitting from the preview never actually sends data ("This preview does not submit" is always shown)
- A form that is not Active (Draft or Archived) shows a note in the preview explaining that it is not currently delivered to guests
- If a phone field has SMS verification enabled, that field cannot be verified in the preview, so the Submit button stays disabled (a note explains why)
- Unsaved edits to "Description for guests" and Status are reflected live in the preview, even before you click Save. The field list itself (enabled/required/choices/order) is auto-saved on every change, so it always reflects the saved state

---

## Feature 4: Public Surveys (Standalone)

Standalone-scope forms are accessible at a public URL without login.

### Setup Steps

1. Create a form with the "Standalone (Public URL)" scope
2. Set a public URL slug (e.g., `satisfaction-survey-2026`)
3. Set the form status to "Active"
4. Share the following URL:
   ```
   /form-demo?facility=<facility-id>&slug=<slug>
   ```

### Common Use Cases

- Satisfaction survey QR codes in the facility
- Post-event attendee feedback
- Facility tour or viewing request forms

---

## Feature 5: Reservation Approval (Manual Approval Mode)

When a plan's `approval_mode` is set to manual, guest reservations enter `pending_approval` status and do not confirm until a facility owner approves them.

### Approval Flow

```
Guest books → pending_approval
  ↓ Owner approves → confirmed
  ↓ Owner rejects → cancelled
```

### Approval Steps

1. Main menu → select "Reservation Approvals"
2. All pending reservations are listed
3. Click "Approve" on a reservation card to confirm it
4. Click "Reject" to show the rejection reason input
5. Enter a reason and click "Confirm Rejection"

For more details, see [Reservation Approvals](reservation-approvals.md).

---

## Migrating from the legacy Guest Form tab

The "Guest Form" tab inside Reservation Management (previously at `/booking?tab=guestForm`) was **removed on 2026-05-19**.

| | Legacy Guest Form tab | New Form Management (`/forms`) |
|--|------|------|
| Forms per facility | One only | Multiple |
| Scopes | Reservation only | Reservation, Identity, Space, Facility, Standalone |
| Per-plan switching | Not available | Attach a different form per plan |
| Public surveys | Not available | Accessible by URL via slug |
| Data migration | — | Automatic (migrated as Default Reservation Form) |

Edits made via the legacy tab were automatically picked up as "Default Reservation Form" and are now edited from `/forms`. The same data continues to back the existing flows.

---

## Frequently Asked Questions

### Q: What happened to my existing Guest Form settings?

They were automatically migrated to "Default Reservation Form" in the new form management. All settings are preserved.

### Q: Can I attach multiple forms to a single plan?

It is recommended to attach one form per plan. Priority behavior when multiple bindings exist is not yet defined.

### Q: Where can I view standalone form responses?

Response viewing and CSV export are planned for a future release. Direct viewing from the admin panel is not yet available.

### Q: Where did the legacy Guest Registry (宿泊者名簿) page go?

The legacy Guest Registry has been folded into Form Management. Open the Forms list, then open **Form Responses Hub** — the "Guest Registry" quick-access card filters responses from the Default Reservation Form, with the same date range filter and CSV export as before. Per-form response browsing is also available from the dropdown.

### Q: What happens when I archive a form?

Archived forms remain in the list but stop appearing in their linked contexts. No data is deleted.

### Q: Can I change whether default fields are required?

Yes. All 11 default fields in reservation-scope forms support toggling between required and optional. You can also enable or disable each field, and reorder them freely. Note that the Required toggle is only available when a field is enabled — enable it first if it is currently disabled.

### Q: Will a guest be asked to re-enter a form at check-in if they already filled it in at booking?

No. When an answer is already recorded for the reservation, **that form is not shown again at check-in for the same reservation**. Booking and check-in are treated as consecutive steps of the same stay, so the guest is never asked to re-enter within one reservation regardless of the reuse policy. The form still appears at check-in for walk-ins (direct check-in) or for reservations where the form was not filled in at booking.

### Q: Most of my default fields on a new reservation form are "Disabled" — is that expected?

Yes. A newly created form starts with only "Full Name" enabled; the other 10 fields (address, nationality, passport photo, and so on) all start disabled. UnlockOS is used across many business types, not only accommodation, so we expect you to enable only what you need. Turn on whatever fields you need with the "Enabled" toggle in the field list.

### Q: What's the difference between "Description for guests" and "Memo (internal)"?

"Description for guests" is shown directly to the guest at the top of the form. "Memo (internal)" is only shown in the admin panel and is never seen by guests. Mixing them up means an internal note leaks to guests (or the explanation you meant for guests never appears), so double-check which field you filled in before saving.

### Q: When should I use the "Checkbox (consent)" field type?

Use it when you need the guest to **agree to a condition** — for example, "This plan is women-only" or "Bringing a pet requires agreeing to an additional policy" — rather than to collect an attribute like gender. A required checkbox always asks the guest to check it again on every submission, regardless of the reuse policy, so a previous consent can never be silently carried forward past the confirmation screen.

### Q: Can the preview show something different from what guests actually get?

Yes, in one case. Field-list toggles (enabled/required/choices/order) auto-save immediately, so the preview always matches what's live. But **form name, description for guests, and status are confirmed by the "Save" button** — unsaved edits to those are reflected live in the preview. If you leave the page before saving, guests will not see that change.

---

## Related Pages

- [Reservation Approvals](reservation-approvals.md)
- [Booking Dashboard](reservation.md)
- [Pricing Plan Configuration](plan-form.md)
- [Check-in Configuration (form timing and path-specific settings)](checkin-config-form.md)
- [SMS Phone Verification (field-level setup)](sms-verification.md)