# Setting up the property profile

The field pool, the structure and the Express, Full and Continuation forms; the built-in fields to use instead of custom copies; field options, show-when rules, translations and publishing.
Page: https://app.proptonomy.ai/docs/property-profile

## How the profile fits together (https://app.proptonomy.ai/docs/property-profile#how-it-fits)
One field pool, one structure, three owner forms. Owners only ever see a form that was published from the structure.
- Field pool: Every fact Proptonomy can hold about a property. Built-in fields come with every organisation; custom fields are the ones the organisation adds. A field in the pool is not asked of anyone until it is placed in the structure.
- Structure: The organisation's one shared list of what owners are asked, sorted into groups (the sections owners see) and ordered. Each placed field also carries whether it is required, its show-when rule and whether the short Express form asks it.
- Express form: The short first form. It asks only the structure fields marked used in Express that an owner may supply.
- Full form: Every structure field an owner may supply, in structure order. Fields provided by the PM are never asked in an owner form.
- Continuation: The rest of the Full form after an owner has started: the same structure and settings as Full, skipping what is already answered and opening at the first unanswered question.

Edit it in Settings → Owner onboarding (Profile for the structure, Fields for the field pool, Forms for the generated owner forms). Editing the pool or the structure saves a draft. Owners keep getting the last published version until someone publishes again (see Drafts and publishing below).

## Built-in fields (https://app.proptonomy.ai/docs/property-profile#built-in-fields)
Built-in fields write straight into the property record, the owner's contact and what Proptonomy sends to the PMS. A custom copy of one stores its answers somewhere nothing reads.

Limit: Always use the built-in field when one exists. Proptonomy refuses a new custom field whose key or label is a built-in field’s key, its label (including a label your organisation gave it) or a common way of asking the same question in English, Norwegian or German, for example How will guests access the property? for `accessMethods` or Nøkkelboks kode for `lockboxCode`. Renaming a custom field into one is refused the same way. Add the built-in field to the structure instead. A different fact that only sounds close, such as the type of lock on the key box or extra access notes, is still allowed. One exception: the key `description` is refused, but a custom field labelled just Description is allowed, because it usually describes something specific rather than the listing.

The keys never change; the labels are the defaults and an organisation can reword them. Fields marked PM are set by the PM, never asked in an owner form, and in a new organisation they sit in the staff-only Listing settings group.
- nickname: Property name. Identity and address.
- propertyType: Property type, such as Apartment, House or Cabin. Only a type from the supported list is saved. Needed for the listing.
- addressStreet: Street address. Needed for the listing.
- addressCity: City. Needed for the listing.
- addressPostalCode: Postal code. Needed for the listing.
- addressCountry: Country. Needed for the listing.
- unitNumber: Unit or apartment number.
- floor: Floor number (a number).
- bedrooms: Number of bedrooms. Per-room questions repeat for each bedroom.
- bathrooms: Number of bathrooms. Per-room questions can repeat for each bathroom.
- areaSquareMeters: Size in square meters.
- doorCode: Door code. Secret, never shown to guests. Needed for the listing.
- alarmCode: Alarm code. Secret, never shown to guests.
- lockboxLocation: Where the lockbox is. Secret, never shown to guests. Needed for the listing.
- lockboxCode: Lockbox code. Secret, never shown to guests. Needed for the listing.
- wifiName: Wi-Fi network name.
- wifiPassword: Wi-Fi password. Secret.
- parkingInstructions: Parking instructions (long text).
- specialEntryNotes: Special entry notes for staff (long text). Secret, never shown to guests. Needed for the listing.
- lockType: Lock brand or system, as free text. It is not how guests get in; that is accessMethods.
- accessCodeRotation: Whether the code guests use for the unit's door or keybox (not a building entrance code) changes between guests: PerStay (new code for every booking), Fixed or Periodic (a select). Not a secret. With PerStay the AI never gives a guest the code stored on the property; a code it reads in one guest's thread is only saved on the property when this is Fixed.
- accessMethods: How guests get in, one or more of Keybox, Keypad, Smart Lock / App, Key handover, Key pickup and Reception. The PMS push needs a confirmed access method. Needed for the listing.
- entranceLocation: Where exactly the entrance is, as a Map pin (mappoint). Asked in the Full form by default, not required. Guests and cleaners get the approved pin as a Google Maps link. Not a secret.
- accommodates: Guest capacity (a number). Needed for the listing.
- basePrice: Base price per night. PM. Needed for the listing.
- currency: Currency. PM. Needed for the listing.
- cleaningFee: Cleaning fee. PM.
- minNights: Minimum nights. PM.
- maxNights: Maximum nights. PM.
- checkInTime: Check-in time. PM.
- checkOutTime: Check-out time. PM.
- roomType: Room type: Entire home/apt, Private room or Shared room. PM.
- hasElevator: Whether there is an elevator (Yes/No).
- description: Listing description (long text).
- spaceDescription: The space (long text).
- accessDescription: Guest access: what guests can use (long text).
- neighborhoodDescription: The neighborhood (long text).
- transitDescription: Getting around (long text).
- houseRules: House rules (long text).
- otherNotes: Other notes (long text).
- generalNotes: General notes, internal and never shown to guests (long text).
- owner.fullName: Owner full name, saved on the owner's contact.
- owner.firstName: Owner first name, saved on the owner's contact.
- owner.lastName: Owner last name, saved on the owner's contact.
- owner.email: Owner email, saved on the owner's contact.
- owner.phone: Owner phone, saved on the owner's contact.
- owner.residentialAddress: Owner residential address, saved on the owner's contact.
- owner.payoutAccount: Owner payout account. Secret, provided by the owner.
- owner.preferredLanguage: Owner preferred language, saved on the owner's contact.
- owner.preferredStartDate: The date the owner wants to start (a date), provided by the owner.

## Field options (https://app.proptonomy.ai/docs/property-profile#field-options)
Set when a field is created and changed later in the pool. Type and per-room source are fixed once the field exists.
- key: Lowercase letters, digits and underscores, starting with a letter, such as tourist_tax. Unique in the organisation, archived fields included, and never a built-in name. It cannot change.
- type: text, textarea (long text), boolean (Yes/No), select (choices), number, date, url, file, mappoint (Map pin) or perRoom. It cannot change.
- knowledge field: Give a knowledge title and the answer is kept as a knowledge base article with that title. It is long text.
- media field: Give mediaKind photo, video, document (a PDF or an image) or any, and minimumMediaCount, from 1 to 1000 (default 5): how many files make the field answered.
- options: The choices of a select field, one per line. Changing the choices clears translated choice captions unless new translations are given at the same time.
- isMultiple: A select field that takes several answers. accessMethods always takes several.
- mappoint: A Map pin: the owner marks up to five spots on a map that opens at the property's address, such as the entrance, the key box or the bins. Each approved pin reaches guests as a Google Maps link.
- perRoom: A question asked once for each bedroom (perRoomSource bedrooms, the default) or each bathroom. Each answer stays bound to its room. perRoomAnswerType is text (default), number, or choice, a dropdown of the field's options. Changing the answer type keeps saved answers.
- required: Set where the field is placed in the structure. The owner must answer it before submitting, but only while its show-when rule holds.
- usedInExpress: Set in the structure: whether the Express form asks it. When a field is added without a choice, it starts from neededForListing.
- neededForListing: The PMS cannot create the listing without it. Listing readiness only; it does not make the owner answer it.
- providedBy: Who supplies the fact: Either (default), Owner or Pm. Pm fields never appear in owner forms.
- purpose: Why it is collected: any of Listing, Operations and Guest.
- isSecret: Codes and passwords guests must never see. Making a field secret or hidden from guests also protects questions on hand-made forms straight away, without publishing.
- isGuestVisible: Whether the value may be shown to guests.
- translations: Per language, keyed by the English language name (Norwegian, German, not no or de): label, help text, placeholder and choice captions in the same order as the choices. A change replaces the whole map, so keep the other languages.
- aiGuidance: Up to 2000 characters for the AI when an owner asks about the field: what owners get wrong, what a good answer is. Only staff and the AI see it. It applies immediately, without publishing.
- inferYesFromAccessMethods: Custom Yes/No fields only: the access methods (keybox, keypad, smartLock, keyHandover, keyPickup, reception) that mean Yes, so the owner is not asked. With an unknown access method the question stays.

## Show-when rules (https://app.proptonomy.ai/docs/property-profile#show-when)
A rule on a placed field decides whether owners are asked it at all.
- A rule names another pool field, an operator and a value: parking equals Yes. The operators are `equals`, `notEquals`, `contains`, `greaterThan` and `lessThan`. On a multi-choice field, equals and contains mean the answer includes the value.
- While the rule does not hold, the question is hidden and never counts as missing. A required question with a rule is required only while the rule holds.
- For access, compare against `accessMethods` with a method key, such as `keybox`, not with a custom access question.
- A question cannot depend on its own answer, and rules cannot go round in a circle. The settings page can combine several rules with all (AND) or any (OR), and so can the assistant (showWhenRules with showWhenMatch all or any). A rule can also test an amenity: the property has it (equals) or lacks it (notEquals). Every field a rule tests must be in the structure (or be a built-in field), and a choice field’s value must be one of its options.

## Group headings and the photo step (https://app.proptonomy.ai/docs/property-profile#headings-and-photos)
What owners read above each group, and on the built-in listing-photo step.
- A group’s English title is its name in the structure. Each other language gets its own title and optional intro; an English entry with only an intro adds an intro for English readers. Languages are named in English, such as Norwegian or German. A change replaces that group’s whole language map.
- The photo step can carry the organisation’s own intro (up to 1000 characters), a guidelines heading (up to 120) and up to 20 guidelines of 300 characters each, plus translations of all three. Blank parts fall back to the standard text. Express and Full have their own photo settings; Continuation uses Full’s.
- It can also show up to 12 example pairs, each a room with an “Avoid” photo and a “Do this” photo and an optional caption on each (room up to 60 characters, captions up to 200). Owners see them above the photo tips, one tab per room. Upload the photos in Settings → Owner onboarding, on the Forms tab; there is no upload tool for them, so `UpdateProfileFormSettings` can reorder, recaption or remove pairs but only reuses photos already in the form. Translations of a pair’s room and captions are keyed by the pair’s id, so keep the id when you send the list back.
- Each of Express and Full also sets which built-in steps it shows (property basics, rooms, amenities, listing photos), the minimum number of listing photos, whether missing photos block submission, and which amenities it offers.

## Drafts and publishing (https://app.proptonomy.ai/docs/property-profile#publishing)
Nothing reaches owners until the form is prepared.
- Every change to the pool or the structure, and to headings and form settings, saves a draft. Each form has a draft version (a hash) that changes whenever the draft does.
- Prepare Express publishes the Express form. Prepare Full publishes the Full form and Continuation. Preparing one does not publish the other.
- Before publishing, the preview lists what changes for owners compared with the live form: questions added, removed and changed, heading and setting changes. When the draft differs only in things owners never see, it says publishing changes nothing for owners.
- Publishing keeps existing answers and links. A question whose field left the structure is retired, not deleted, and its answers stay.
- Wording for the AI (aiGuidance) applies immediately and needs no publishing.

## Who can change the profile (https://app.proptonomy.ai/docs/property-profile#who-can-change)
Only admins change it, in Settings, through the in-app assistant and through Claude or another AI over MCP.
- Admins and members of the organisation can read the profile, in Settings and through the assistant. Members see Settings read-only.
- Changing it through the assistant needs an admin who is signed in to Proptonomy. The assistant asks the PM to confirm each change; publishing, importing a form and adopting the access field do nothing without confirm=true, and publishing also needs the draft version the PM reviewed.
- Every change, in Settings or through the assistant, needs an organisation admin: fields, structure, headings, form settings, importing a form and publishing.
- The assistant can archive a custom field only after a preview and the PM’s confirmation. It cannot archive built-in fields or profiles, and it writes a property’s values only when moving a custom field onto a built-in, and then only where the built-in value is empty.

## Common changes, step by step (https://app.proptonomy.ai/docs/property-profile#recipes)
The tool calls the assistant makes, in order. Every change is confirmed with the PM first.
1. Check the setup first. Call `CheckProfileSetup`. It lists custom copies of built-in fields, show-when rules that can never hold, missing translations in the languages your owners use, required Express questions that depend on fields Express does not ask, custom fields nothing asks and unpublished forms, each with the call that fixes it.
2. Add a question. Call `SearchProfileFields` with the question’s subject. If a built-in field covers it, place that field with `AddFieldsToProfileStructure` and its key. Only when nothing fits, create a field with `CreateProfileField`, then place it the same way.
3. Move a question. Call `UpdateProfileStructureField` with the field key and a new group, an afterFieldKey, or both.
4. Make it conditional. Call `UpdateProfileStructureField` with showWhenFieldKey, showWhenOperator and showWhenValue, or with showWhenRules and showWhenMatch for several rules. clearShowWhen removes the rule.
5. Translate. Read the current translations first, then send the whole map. Use `UpdateProfileField` for questions and `UpdateProfileGroupHeading` for group headings. For the photo step use `UpdateProfileFormSettings` with that form’s draftHash from `GetProfileStructure` as the expected version.
6. Fix a custom access question. Call `AdoptBuiltInAccessField` with the custom field’s key and show the PM the option mapping it returns; choices it cannot place stop the change. With confirm=true it moves the question onto accessMethods in the same group, order and required setting, points show-when rules at accessMethods, fills each property’s access method from its answer without overwriting one already confirmed, and archives the custom field. Publish afterwards.
7. Fix any other custom copy of a built-in field. Call `AdoptBuiltInField` with the custom field’s key and the built-in key, for example lockboxCode. The custom field’s type must fit the built-in one: a free-text answer cannot become Bedrooms. The preview gives the counts; with confirm=true it moves the question onto the built-in field in the same group, order and required setting, points show-when rules at it, binds the questions on forms to it, fills each property’s built-in value from its answer only where that value is empty, and archives the custom field. A form question whose type cannot hold the built-in fact, or a rule that would make the built-in depend on itself, stops the change; a profile that already asks the built-in keeps it.
8. Rename, reorder or delete a group. `RenameProfileGroup` keeps the group’s fields and heading translations under the new name. `ReorderProfileGroups` takes every group name once, in the new order. `DeleteProfileGroup` moves the group’s fields into moveFieldsToGroup; it previews first and applies with confirm=true.
9. Archive a custom field. Call `ArchiveProfileField`. The preview says how many properties hold a value and which groups ask it; with confirm=true the field leaves every profile and its values are kept. Built-in fields cannot be archived (take them out of the structure with `RemoveFieldFromProfileStructure`), and show-when rules that depend on the field must be cleared first. While a live form still asks the field, remove it from the structure and publish, or remove the question from a hand-made form, first.
10. Publish. Call `PrepareProfileForm` with Express or Full and show the PM the changes it lists. After they confirm, call it again with confirm=true and the expectedDraftHash from that preview.