Click "+ Smart book" on /portal/schedule to open the Smart Book composer. It's the same engine the AI receptionist uses when a customer calls — the same tech-skill match, the same geographic ranking, the same capacity checks — but surfaced as a modal so you can run it yourself when booking over the phone or at the counter.
On Voice or Visibility plans, the composer still works but returns time-only ranked slots (next open slot, no geographic optimization). The geographic "minimize tech's detour" ranking kicks in on Bundle and Front Office when you provide a service address.
Step 1 — Customer
The first thing to decide is whether this is an existing customer or a new one. Two buttons at the top of the modal switch modes:
- Existing customer: a search box appears. Type a name, email, or phone number. Results appear as you type — there is no "show all" dropdown, just search-as-you-type capped at 12 results. Select a result and the form pre-fills with their address and contact info.
- New customer: form fields are blank; you fill them in. A new customer row is created in the customers table when the appointment is saved.
If you're booking an existing customer and their phone or address has changed — say they moved — just update the fields while the customer is on the phone. The diff gets written back to their customer record when you confirm the booking. No need to separately go to /portal/customers to update it.
Step 2 — Service address
The address field is split into structured components — not a single freeform blob:
| Line 1 | Street number + street name (required for geocoding) |
| Line 2 | Unit / apt / suite (optional) |
| City | City name |
| State | 2-letter state abbreviation (auto-uppercased) |
| ZIP | Postal code |
The address is geocoded server-side when you click "Find best slots". The lat/lng powers the geographic ranking — which tech's next stop is closest to this address. Geocoding is cached, so repeat visits to the same address are fast.
Address is optional for the time-only mode (no Bundle plan) but the label on the address field changes to "required for smart ranking" when smart scheduling is active to hint that leaving it blank degrades slot quality.
Step 3 — Service and duration
Type the service name (e.g. "AC tune-up", "drain clear"). The duration defaults to 60 minutes. Both fields are freeform — the service name drives skill-matching against your services catalog if there's a match, and the duration controls how much time gets blocked on the tech's calendar.
Prefer tech: optional dropdown. When filled, the smart-slot ranking biases toward slots on that tech's schedule. Still shows other techs if the preferred tech has no open slots in the window.
Step 4 — Slot ranking
Click "Find best slots". The endpoint returns up to 8 slots in ranked order. The ranking algorithm considers:
- Tech skill match — does this tech's skill keywords cover the requested service?
- Route distance — how far is this appointment from the tech's adjacent stops? Slots that add the least detour distance rank highest.
- Daily capacity — techs at or over their booked hours don't appear.
- Weekly schedule overlap — techs marked off for a specific day don't appear.
- Time-off blocks — techs on approved time off don't appear.
Each slot card shows the date/time, tech name, duration, and (when smart ranking is active) a detour-distance badge:
| On the way (green) | Less than 1 mile of additional driving — this tech is already in the area. |
| +X.X mi (blue) | 1–3 mile detour. Minor. |
| +X mi (amber) | 3–8 mile detour. Reasonable. |
| +X mi (gray) | Over 8 miles. Long detour — still bookable, but there may be a better option later. |
The top result gets a "Best fit" badge. Click any slot to confirm the booking.
When you see "no open slots"
The composer diagnoses why no slots are available and shows a specific callout with a fix link. There are 4 states:
| no_active_techs | No techs in the team roster, or all are deactivated. Link: /portal/team → Add a tech. |
| no_business_hours | Business hours aren't configured, so smart-slot doesn't know what window to search. Link: Settings → Business hours. |
| outside_window | You clicked a specific time on the calendar and there's nothing open in that ±2-hour window. Try a different day or search without a time pre-selected. |
| all_busy | Every tech is fully booked or on time-off for the next 14 days. Links: /portal/team (increase daily capacity) or /portal/time-off (review time-off blocks). |