Pre-check-in Steps

A pre-check-in step is one task a guest completes in the guest portal before arrival: confirming their details, uploading an ID, signing an agreement, paying a deposit, answering questions. Each step is a reusable template in your organization, switched on with isActive and assigned to the properties whose guests should see it. This guide covers the step operations. Every field is listed on the operation’s page in the API Reference.

Operation	Request	Permission
listPrecheckSteps	GET /precheck-steps	view_properties
getPrecheckStep	GET /precheck-steps/{id}	view_properties
createPrecheckStep	POST /precheck-steps	modify_properties
updatePrecheckStep	PATCH /precheck-steps/{id}	modify_properties

Paths are relative to your region’s base URL, for example https://api-us.suiteop.com/api/v1. See Authentication for permissions.

Some writes need modify_tasks as well: minting question text with POST /translations, sending questions that link new or changed translation IDs, and changing a step’s guest-facing title or linked copy on update. See Guest-facing title.

Steps can’t be deleted or duplicated through the API. Set isActive to false to take one off every portal.

Step types

stepType decides what the step asks of the guest and which other fields apply. It is one of your_details, identity_check, background_check, other_guests, authority_reporting, additional_questions, document_upload, agreement, mandatory_fee, damage_deposit, screen_and_protect or main.

Additional questions are single_select, multi_select, free_form_input or yes_no, and a question can be shown only when an earlier question has a given answer.

On an authority_reporting step that files with GuestAdmin, set isGuestAdminPropertyInfoEmailEnabled: true to let GuestAdmin email the lead guest its Property Information email. SuiteOp passes the flag when it creates the GuestAdmin booking, on the guest’s final submission of the step. It defaults to false, is ignored for other providers, and, like other type-specific settings, is not returned when you read the step.

nickname is required on every step. It is an internal label, up to 200 characters, and is never shown to guests.

Guest-facing title

Guests see a heading on each step. By default it is the built-in title for the step type, in the guest’s language. displayTitle replaces it with your own text, up to 200 characters.

• On create, send displayTitle as text. displayTitleLanguage says which language it is written in and defaults to English.
• A step’s first title must be in English. Sending a non-English displayTitleLanguage for a step that has no title yet, on create or update, is rejected with 400 and the message precheck_step.display_title_english_required.
• On update, omit displayTitle to keep it and send null to clear it and go back to the built-in title. Sending displayTitleLanguage with text for a step that already has a title sets that one language, for example the French version, and leaves the others alone.
• displayTitleLanguage needs text. Sending it alone, with displayTitle: null, or with displayTitleMlTextId is rejected with 400.
• displayTitleMlTextId links a translation you already created with POST /translations and sourceTable: "precheck_step_detail" (see Translations). Send either it or displayTitle, not both.
• Reading it back: getPrecheckStep returns displayTitle as text. REST and MCP callers always read the English text. null means no custom title is set and guests see the built-in one. listPrecheckSteps, createPrecheckStep and updatePrecheckStep return only displayTitleMlTextId.
• Permission: an update that sends displayTitle at all, or changes a linked copy ID such as displayTitleMlTextId, needs modify_tasks in addition to modify_properties. Without it the update returns 403.

Listing steps

GET /precheck-steps returns every step in the organization, active and inactive, in one unpaginated array:

curl https://api-us.suiteop.com/api/v1/precheck-steps \
  -H "Authorization: Bearer sk_live_your_key_here"

Each item carries id, nickname, displayTitleMlTextId, stepType, isActive, sortOrder, the damage-waiver and security-deposit settings, and:

• scope: counts of the step’s assignments, as propertyCount, portalCount, propertyGroupCount and tagCount. For the IDs themselves, call GET /entity-scopes.
• configurationIssue: missing_payment_account when an active damage_deposit step has no usable payment account, missing_authenticate_account when an active background_check step has no active authenticate.com account, otherwise null. It is only computed for active steps.
• hasUsableDamageWaiver: true for an active damage_deposit step that offers a damage waiver and has an active account to charge it to, either its own or, when none is set, the organization default.

Filters (all optional):

• propertyIds, propertyGroupIds, portalSettingsIds, tagIds return steps assigned directly to any of the given IDs. A step that reaches a property only through its group, portal or tags isn’t matched by propertyIds. Different filters combine with AND.
• assignment: assigned returns steps with at least one assignment, unassigned steps with none. unassigned together with one of the ID filters always returns an empty list.

The list is in the order guests walk the steps (see Ordering), using the setting of the portal you filter on when portalSettingsIds has exactly one ID, and otherwise the organization’s default portal.

Reading one step

GET /precheck-steps/{id} returns the step with its targeting rules, deposit and agreement settings, displayTitle, updatedAt, and the full questions list with each question’s id, options and conditions.

Several settings can be written but not read back through the API: guestDescriptionMlTextId, contractTemplateText, esignPrefillValues, and every setting specific to identity_check, your_details, other_guests, document_upload, authority_reporting, screen_and_protect, background_check and mandatory_fee. A field missing from the response doesn’t mean the write failed.

Creating a step

POST /precheck-steps creates a step:

curl -X POST https://api-us.suiteop.com/api/v1/precheck-steps \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Idempotency-Key: 6c1f0b9e-2d4a-4e8b-9f37-5a0c7d2e1b64" \
  -H "Content-Type: application/json" \
  -d '{
    "stepType": "your_details",
    "nickname": "Booker details",
    "displayTitle": "Tell us about yourself",
    "isActive": true,
    "sortOrder": 0
  }'

The response is 201 with the new step:

{
  "data": {
    "id": "8d2e4f60-1b3a-4c7d-9e25-0f6a8b1c3d47",
    "nickname": "Booker details",
    "displayTitleMlTextId": "a7c3e9b1-5d2f-4a60-8e14-3b9f0c6d2e85",
    "stepType": "your_details",
    "isActive": true,
    "isEnabled": true,
    "sortOrder": 0,
    "updatedAt": "2026-09-27T10:15:00.000Z",
    "inclusionType": null,
    "excludedSources": null,
    "includedSourcesReturning": null,
    "isAlwaysShown": false,
    "isReturningGuestExcluded": false,
    "leadTimeMinDays": null,
    "leadTimeMaxDays": null,
    "minLos": 0,
    "maxLos": 1000,
    "damageWaiverDepositAmountCents": null,
    "isDamageWaiverEnabled": false,
    "damageWaiverCapCents": null,
    "damageWaiverMinLos": 0,
    "damageWaiverPricingBasis": "per_night",
    "isDamageWaiverWaivable": false,
    "damageWaiverPaymentAccountId": null,
    "damageDepositSubtitleMlTextId": null,
    "securityDepositAmountCents": null,
    "isSecurityDepositEnabled": false,
    "securityDepositDaysBeforeCheckin": null,
    "securityDepositReleaseDaysAfterCheckout": 3,
    "securityDepositPaymentAccountId": null,
    "securityDepositSubtitleMlTextId": null,
    "agreementType": null,
    "contractTemplateTextMlTextId": null,
    "docusignTemplateId": null,
    "docusignTitleMlTextId": null,
    "docusignSubtitleMlTextId": null,
    "documensoTemplateId": null,
    "documensoHeadingMlTextId": null,
    "documensoSubtitleMlTextId": null,
    "isMandatorySigning": false,
    "questions": [],
    "damageWaivers": []
  },
  "meta": { "requestId": "…" }
}

Field notes:

• The step reaches no guest yet. A new step has no assignments. Assign it as described in Choosing which properties use it.
• questions and damageWaivers are always [] in create and update responses. Read them with getPrecheckStep.
• Questions (additional_questions) need translation IDs for their text and option names. Create them first with POST /translations, which needs modify_tasks (see Translations).
• Payment accounts (damageWaiverPaymentAccountId, securityDepositPaymentAccountId and feesPaymentAccountId) come from GET /payment-accounts. An unknown, inactive or other-organization ID returns 404. Sending null does not turn the charge off: the step then uses your organization’s active default payment account.
• background_check and mandatory_fee can’t be completed through the API. No operation lists the authenticate.com accounts or fee products they need, so you have to get those IDs from SuiteOp.
• Use an Idempotency-Key so a network retry doesn’t create a second step.

Review settings

• identityFlagPolicy (identity_check) sets what each identity check does when it finds a problem: ignore skips the check, review sends the guest straight to your team, and fail lets the guest retake once before it goes to your team. Omit a key to keep that check’s default; null clears every override. Six keys accept only their default, and any other value returns 400: document_not_official, selfie_spoof and verification_unavailable (fail), and name_unavailable, name_unconfirmed and retake_limit (review). guest_is_local and guest_underage accept fail but act as review, because a retake can’t change them.
• minimumGuestAge is the age threshold for the guest_underage row, and must be set whenever that row isn’t ignore.
• isPhotoIdRequired is accepted for compatibility but enforces nothing. To reject an ID with no photo of the holder, set identityFlagPolicy.no_face_on_document.
• isManualReviewEnabled (additional_questions, document_upload, damage_deposit): true, the default, holds a flagged submission for staff review. false lets it complete on its own, and no one is asked to review it.

Targeting rules

These fields decide which reservations get the step:

• minLos / maxLos: stay length in nights. 0 means no minimum and 1000 means no maximum. minLos above maxLos is rejected.
• leadTimeMinDays / leadTimeMaxDays: days between booking and check-in. null means no bound. An inverted window is rejected.
• inclusionType: all_except_selected hides the step for the channels in excludedSources; only_selected shows it only for the channels in includedSourcesReturning, which must then be non-empty.
• isReturningGuestExcluded: true skips guests who have stayed before.
• isAlwaysShown: true shows the step to every guest and ignores all the rules above.

Updating a step

PATCH /precheck-steps/{id} takes the fields to change inside a required data object. Fields you leave out keep their value.

curl -X PATCH https://api-us.suiteop.com/api/v1/precheck-steps/8d2e4f60-1b3a-4c7d-9e25-0f6a8b1c3d47 \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "expectedUpdatedAt": "2026-09-27T10:15:00.000Z",
    "data": {"minLos": 2, "isAlwaysShown": false}
  }'

The response is the updated step, in the same shape as the create response.

• Rules are checked against the merged step. Moving one end of a stay-length or lead-time window is rejected when it inverts the stored other end, and turning a step on is rejected when the configuration it needs isn’t there (for example an agreement step without a template or text, or additional_questions without questions).
• questions and feeProductIds replace the whole list. Send every question you want to keep with the id getPrecheckStep gave you, so guest answers already collected stay attached. A question sent without id is created as new. The same holds for each question’s options: send every option back with its id to keep it — workflow answer conditions point at option IDs — because an option sent without id is created fresh and an option left out is deleted. An id that doesn’t belong to this step is rejected with 400. Send [] to clear the list, or omit it to leave it alone.
• expectedUpdatedAt is optional. Send the updatedAt you last read, and the update returns 409 (CONFLICT) if the step changed since. Omit it to overwrite regardless.
• stepType is locked once guests have used the step. Changing it then returns 409 CONFLICT with the message PRECHECK_STEP_TYPE_LOCKED. Deactivate the step and create a new one instead.
• nickname can’t be cleared: null or blank returns 400.

Turning a step on and off

isActive is the switch. It defaults to false, so a step created without it is saved but never shown. Send "isActive": true on create or update to show it, and false to take it off every portal. Turning a step on is when the checks for its required configuration apply.

isEnabled is a deprecated copy of isActive. Leave it out: sending false switches the step off whatever isActive says, and true does nothing.

Choosing which properties use it

A step reaches properties through four routes: individual properties, property groups, tags and guest portals. A portal assignment covers the properties whose effective portal it is: the property’s own portal, else its group’s, else its tag’s, else the organization default. createPrecheckStep and updatePrecheckStep don’t set them. Use the entity scope operations with entityType: "precheck_step" and the step’s id as entityId:

Operation	Request	Effect
listEntityScopes	GET /entity-scopes	Read the current propertyIds, propertyGroupIds, tagIds and portalSettingsIds
updateEntityScopes	POST /entity-scopes	Replace every assignment with what you send
addEntityScopes	POST /entity-scopes/add	Add to the existing assignments
removeEntityScopes	POST /entity-scopes/remove	Remove from the existing assignments

listEntityScopes needs view_properties; the write operations need modify_properties.

curl -X POST https://api-us.suiteop.com/api/v1/entity-scopes/add \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "entityType": "precheck_step",
    "entityId": "8d2e4f60-1b3a-4c7d-9e25-0f6a8b1c3d47",
    "portalSettingsIds": ["c41e7d20-5b8a-4f13-9d62-7e0a3c1b9f58"]
  }'

Ordering

Each guest portal has an “order steps automatically” setting, isPrecheckOrderAutomatic on updatePortal, which is on unless you turn it off (see Guest Portals).

• Automatic (the default): steps run in a fixed order by type: your_details, identity_check, background_check, other_guests and authority_reporting, additional_questions, document_upload, agreement, mandatory_fee, then damage_deposit and screen_and_protect. main runs after all of them. sortOrder only orders steps of the same group.
• Host order: with the setting off, steps run by sortOrder alone.

In both cases ties are broken by creation time, and a step without sortOrder comes last. sortOrder is zero-based.

Property-limited callers

An sk_ API key acts across the whole organization. An OAuth token carries the property access of the member who authorized it (see Members):

• Reading: a limited caller sees a step that reaches at least one of their properties, and any step not yet assigned anywhere. Other steps return 404 from getPrecheckStep and updatePrecheckStep and are left out of listPrecheckSteps. The scope counts only include what the caller can reach.
• Fee products: changing feeProductIds on a step that also serves properties outside the caller’s access returns 403.

Pitfalls

Caution

• A new step is inactive unless you send isActive: true, and a step without assignments reaches no guest even when active.
• A step in another organization, or outside an OAuth caller’s properties, returns 404, not 403.
• updatePrecheckStep needs modify_tasks as well whenever it sends displayTitle, changes a linked copy ID, or links new question copy. Otherwise it returns 403.
• questions, feeProductIds and updateEntityScopes replace the whole list. Sending a question without its id recreates it and detaches the answers guests already gave.
• 409 means either the step changed since your expectedUpdatedAt, or you tried to change stepType on a step guests have already used.
• getPrecheckStep doesn’t return every setting you can write, and create and update responses have no questions or displayTitle.
• Steps can’t be deleted or duplicated through the API. See Errors for the error format.