Configure

People directory

The directory is your roster of people — the staff your AI is allowed to know about by name. Once someone is in it, the AI can recognise them when a visitor asks for them, add them as a required attendee on a booked meeting, take that meeting’s hours and timezone from them, and (on Scale) connect a live phone caller to them.

What it is for

Four different features read the same roster, which is why it lives in one place rather than being retyped into each of them:

• Meeting attendees — on Personas → Tools you can name the people who must be on every booked meeting. Type a name and pick from the directory instead of retyping an address. The booker checks their calendars too, so a time is only offered when the whole room is free.
• Booking hours — a person’s own timezone and working_hours are the first thing the booker consults when deciding what to offer. Give a rep in Berlin their own working_hours and those are what get offered, even though the brand is in Chicago. Setting only their timezone does something narrower — see Working hours and timezone below. See Locations for how the fallback chain works.
• Caller recognition (Scale, or the add-on) — when a caller asks for “Dr. Nguyen”, the AI can look that name up against the roster mid-call, including nicknames and common misspellings.
• Call transfer (Scale, or the add-on) — connect the caller to that person’s number, with a screened whisper so they can accept or decline. See Phone numbers.

Add people

• Dashboard — open Directory in the sidebar and click Add person. Full name and email are the only required fields; everything else is optional.
• CSV — paste a sheet into the import box. Recognised columns are external_ref, display_name, aliases, title, department, phone_e164, extension, room_or_unit, sip_uri, email, transfer_mode, max_ring_seconds, respect_location_hours, fallback, message_to, visibility, valid_until, timezone and notes. Any other column is reported back and ignored, so you can paste a wider export without editing it down. Cap is 500 rows per import.
• API — POST /api/v1/directory-entries, or /bulk for a whole roster. See API & webhooks.

Identity: use your own ids

Every surface addresses a person by external_ref — your id from your HR system, PMS, or spreadsheet. GET ?external_ref=, POST {"upsert": true} and /bulk are all keyed on it, so a nightly full-roster sync is idempotent: re-running it updates the people who changed and leaves the rest alone, instead of creating duplicates.

Working hours and timezone

These two fields are what make a person’s meetings land at a sane local time.

• timezone — an IANA zone such as Europe/Berlin. It says where this person is. On its own it does not move their location’s booking hours into their clock — hours are always read in the clock of whoever set them. What it does is tell us whether those hours describe this person at all. If it puts them somewhere else than their location, the location’s hours are still used to suggest times but will no longer refuse a time the visitor asks for; if it puts them on the same clock as the location — the ordinary single-timezone case, and alternative spellings like US/Central and America/Chicago count as the same clock — nothing changes and those hours still apply in full. Either way, a rep who keeps their own office hours needs their own working_hours below for those to be offered and enforced. Set it via CSV import or the API.
• working_hours — requires timezone to be set on the same person (they are wall-clock times). When this person takes meetings, as {"mon":[["09:00","17:00"]], "sat":[["10:00","14:00"]]}. Day keys are mon…sun; times are 24-hour HH:MM, capped at 12 ranges a day. Leave it unset and the person inherits their location’s booking hours. It is a nested object rather than a cell value, so it is set via the API only — not CSV.

Hours that cannot be parsed are rejected rather than stored: a typo’d import that was accepted and then silently ignored would quietly take someone’s calendar back to the default 9–5, and you would have no way to tell from the screen.

Visibility

Being in the directory does not mean the AI will volunteer someone’s name. Each person has a visibility, and the default is the most private one:

• hidden (default) — never surfaced. The person exists for attendee and hours purposes but the AI will not confirm they work here.
• unlisted_connectable — the AI will connect a caller who already knows the name, but will never confirm the person’s presence to someone fishing.
• listed — disclosable; the AI may name them.

Transfer behaviour

Per person, for phone calls (Scale, or the add-on):

• transfer_mode — screened (warm transfer with a press-1 whisper), message (take a message, never ring), or none (recognise-only).
• max_ring_seconds — 5–120, how long to ring before giving up.
• fallback — what happens when they do not pick up: message, ai (hand back to the AI), or hangup.
• respect_location_hours — on by default, so an 11pm caller is not put through to a dark office.
• valid_until — an expiry. Useful for a locum, a contractor, or a hotel guest: past that date the person stops being matched, with no cleanup job to remember. It revokes every path, not just search — they are no longer added to meetings as an attendee, no longer offered in the attendee picker, and calls are no longer transferred to their number. Note that a date with no time means the start of that day, so “valid until 31 December” ends on the 30th.

Locations and who can see it

The Directory screen is for owners, admins and viewers. A viewer reads the roster and changes nothing — adding, editing and removing people stay with owners and admins. Agents can’t read it at all: it carries staff phone numbers and personal addresses, including people you’ve marked hidden.

A person can be attached to a location or left brand-wide. If you have given a manager a location scope on Team & roles, they see and manage only their locations’ people — that applies to the list, the search, and to adding, editing and deleting. Brand-wide people are visible to every manager, since they aren’t any one branch’s data.

Tips

• Fill in aliases for anyone who goes by a shortened name. “Bao”, “Dr. N” and a maiden name all cost nothing and are the difference between a match and an apology.
• Set timezone on anyone who is not where their location is. It says where they are, which is what stops that location’s hours from turning a booking down for them — but on its own it does not put the offered times into their clock. Hours are always read in the clock of whoever set them, so once any location supplies booking hours, those hours and that location’s zone are what the agent talks in. For a remote hire who keeps local office hours, add working_hours too: the timezone alone says where they are, not when they work.
• Keep visibility at hidden unless you actively want the AI naming that person to strangers. Attendees and hours work fine while hidden.
• Sync rather than curate. If the roster lives in an HR system, point a nightly /bulk upsert at it and let leavers fall out via valid_until.