Portals - Conduit

Portal tools require the Portals add-on. Without it every portal tool returns a forbidden error. Contact support@conduit.ai to enable it.

Overview

A portal is the page someone gets a link to before their stay. What they see there comes from three pieces of workspace configuration, each with its own set of MCP tools:

Verification rules

What has to be collected or signed before check-in. Deposits, agreements, arrival details, questions.

Offers

The things that can be bought or requested. Late checkout, mid-stay clean, airport pickup.

Templates

The page itself: branding, layout blocks, and which offers appear where.

These are independent. You can ship verification rules without ever building a template, and offers exist on their own until a template’s layout references them.

Before you start

Requirement	Detail
Token	Read/write for any create, patch, delete, or reorder. Read-only tokens can list and get.
Permission	`View Upsells` to read, `Manage Upsells` to write.
Argument	Every tool takes `workspace_id`.
Concurrency	Every write takes `expected_updated_at` (or `expected_version` on templates).

All timestamps are epoch milliseconds. All money is whole cents (25000 is $250.00) paired with a lowercase currency code.

Verification rules

A verification rule says “for stays that look like this, collect this before check-in.” Each rule has a step type (what to collect), a config (how to present it), and optional targeting (which stays it applies to).

Step types

`step_type`	Slot	Collects
`id_check`	`identity`	An identity document.
`agreement`	`agreement`	A signature on a document. Never priced.
`damage_waiver`	`signature`	A signature on a waiver, optionally priced.
`security_deposit`	`deposit`	A refundable hold.
`mandatory_fee`	`fee`	A non-refundable charge.
`guest_details`	`guest_details`	Email, phone, arrival and departure times.
`additional_questions`	`questions`	Free-form questions you define.
`other_guests`	`other_guests`	Details for everyone else on the booking.

The rule that governs everything: one rule per slot

Rules are evaluated in order. For each slot, the first enabled rule whose targeting matches the stay wins, and every later rule for that slot is skipped. This is what makes ordering meaningful. A specific rule has to sit above the general one, or it never fires:

order 1  Deposit, stays of 7+ nights, $500     <- matches a 10-night stay, claims "deposit"
order 2  Deposit, every stay, $250             <- skipped for that stay, applies to the rest

Flip those two and the $500 rule becomes dead configuration: the catch-all claims the slot first, every time. Nothing errors, the specific rule just never applies. Two rules with different step types that share a slot compete the same way. damage_waiver and agreement do not, they sit in different slots and both apply.

Creating a rule

Start with the simplest useful one, arrival details on every stay. Omitting targeting means “every stay”:

{
  "name": "Arrival details",
  "workspace_id": "ws_123",
  "step_type": "guest_details",
  "config": {
    "title": "When are you arriving?",
    "collectEmail": true,
    "collectPhone": true,
    "collectEta": true,
    "collectEtd": false,
    "requiredFields": ["phone", "eta"]
  }
}

requiredFields must be a subset of what you collect. Requiring eta while collectEta is false is rejected. Now a targeted, priced one. This is where the ordering rule starts to matter:

{
  "name": "Deposit on long stays",
  "workspace_id": "ws_123",
  "step_type": "security_deposit",
  "config": {
    "title": "Security deposit",
    "instructions": "Released 7 days after checkout.",
    "amountInCents": 50000,
    "currency": "usd",
    "releaseDelayDays": 7
  },
  "targeting": {
    "minNights": 7,
    "bookingChannelMode": "exclude",
    "bookingChannels": ["airbnb"]
  }
}

New rules are appended last and enabled by default. Since this one is more specific than a catch-all deposit, move it up (see Reordering).

The other five step types

Agreement. A document to sign, with no charge attached. Pricing an agreement is rejected; use damage_waiver instead.

{
  "step_type": "agreement",
  "config": {
    "title": "House rules",
    "body": "Quiet hours are 10 PM to 8 AM. No smoking anywhere on the property."
  }
}

Damage waiver. A signature that can carry a price. model is flat or per_night; capInCents bounds a per-night total and must be at least amountInCents.

{
  "step_type": "damage_waiver",
  "config": {
    "title": "Damage waiver",
    "body": "Covers accidental damage up to $1,000.",
    "pricing": {
      "model": "per_night",
      "amountInCents": 1200,
      "currency": "usd",
      "capInCents": 8400
    }
  }
}

Mandatory fee. Same shape as a deposit but non-refundable, so no releaseDelayDays.

{
  "step_type": "mandatory_fee",
  "config": {
    "title": "Resort fee",
    "instructions": "Covers pool and gym access.",
    "amountInCents": 3500,
    "currency": "usd"
  }
}

Additional questions. Question ids must be unique within the rule. single_select and multi_select need at least two options; text, long_text, and checkbox take none.

{
  "step_type": "additional_questions",
  "config": {
    "title": "A few questions",
    "questions": [
      {
        "id": "purpose",
        "label": "What brings you here?",
        "type": "single_select",
        "required": true,
        "options": ["Holiday", "Work", "Family"]
      },
      {
        "id": "plate",
        "label": "Vehicle plate, if you are driving",
        "type": "text",
        "required": false
      }
    ]
  }
}

Other guests. Details for everyone else on the booking. Set minGuests, maxGuests, or both. maxGuests caps at 50 and fields caps at 20 entries, each with a unique id.

{
  "step_type": "other_guests",
  "config": {
    "title": "Who else is staying?",
    "maxGuests": 6,
    "fields": [
      { "id": "full_name", "label": "Full name", "type": "text", "required": true },
      { "id": "photo_id", "label": "Photo ID", "type": "image", "required": false }
    ]
  }
}

ID check. Collects an identity document. Takes title and instructions, plus optional requireContactPhoto and autoApprove.

Targeting

Every criterion you set is ANDed. An empty or omitted targeting matches every stay.

Field	Effect
`minNights` / `maxNights`	Stay length bounds. `minNights` cannot exceed `maxNights`.
`bookingChannels` + `bookingChannelMode`	`include` or `exclude` the listed channels. Setting a mode requires at least one channel.
`maxBookingLeadDays`	Only bookings made within this many days of arrival.
`matchUnknownBookingLeadTime`	Also match stays with no known booking date. Requires `maxBookingLeadDays`.
`listingIds` / `listingGroupIds`	One location filter: the stay passes if its listing is listed or one of its groups is.

exclude_returning_guests sits alongside targeting and drops the rule for anyone who has stayed before. Useful for ID checks you only want to run once per person.

Reordering

reorder_verification_rules takes every rule in the workspace, in the order you want, each with its expected_updated_at. Partial lists are rejected:

{
  "workspace_id": "ws_123",
  "items": [
    { "id": "vr_long_stay_deposit", "expected_updated_at": 1730000000000 },
    { "id": "vr_standard_deposit", "expected_updated_at": 1730000000000 },
    { "id": "vr_arrival_details", "expected_updated_at": 1730000000000 }
  ]
}

Omitting a rule would silently renumber the ones you left out, which is exactly how a specific rule ends up buried under a catch-all. Send the whole list.

Editing and deleting

patch_verification_rule cannot change step_type. A config you send has to match the type the rule already has, or you get invalid_input. An agreement or damage_waiver rule whose document was uploaded in the app rejects a config for the same reason: edit its PDF in the app. delete_verification_rule is permanent: stays already collecting that step keep what they have gathered, new stays stop being asked.

Priced rules (security_deposit, mandatory_fee, and damage_waiver with a non-zero price) need Stripe connected before they can be enabled, but only once the workspace has an active template. Until then you can build them freely.

Portal offers

An offer is one purchasable or requestable thing. Offers are workspace-level and reusable: create one, reference it from as many template layouts as you like. kind decides the behaviour: purchase takes payment, request asks without charging, ad just links out via link_url.

Flat pricing

{
  "workspace_id": "ws_123",
  "name": "Late checkout",
  "description": "Keep the room until 2 PM.",
  "price_in_cents": 3500,
  "kind": "purchase",
  "highlights": ["Two extra hours", "Subject to availability"]
}

Priced by option

When one offer has variants, use by_option pricing. fieldLabel is what the chooser is called, and each option carries its own price:

{
  "workspace_id": "ws_123",
  "name": "Airport pickup",
  "description": "Meet and greet at arrivals.",
  "price_in_cents": 6000,
  "kind": "purchase",
  "pricing": {
    "model": "by_option",
    "fieldLabel": "Vehicle",
    "options": [
      { "title": "Sedan, up to 3 bags", "priceInCents": 6000 },
      { "title": "Van, up to 7 bags", "priceInCents": 9500 }
    ]
  }
}

by_option requires both fieldLabel and options. Omitting either is rejected.

Pricing off the booking total

percent_price charges a percentage of a booking figure instead of a fixed amount:

{
  "percent_price": { "percent": 10, "of": "totalPrice" }
}

of accepts totalPrice, grossRent, netRent, subtotal, totalFees, or totalTaxes.

Targeting and availability

Offer targeting takes listingIds, listingGroupIds, inboxTypeIds (with inboxMode), night bounds, vacancy windows (minVacantNightsBeforeArrival, minVacantNightsAfterDeparture), and customAttributeConditions combined with all or any. Early checkin, for instance, only makes sense when the night before is free:

{
  "targeting": { "minVacantNightsBeforeArrival": 1 }
}

availability bounds when the offer is visible and bookable using visibleFrom, visibleUntil, bookableFrom, and bookableUntil.

Archiving

archive_portal_offer deactivates an offer and removes it from every template layout that referenced it. restore_portal_offer reactivates it but does not put it back into those layouts; re-add the blocks yourself.

Portal templates

A template is the page. It carries branding, a header, an ordered layout, and checkout behaviour.

Status and versioning

Templates are draft, active, or paused (plus archived). A new template starts as draft unless you say otherwise. Templates use expected_version, an integer, rather than a timestamp.

Editing a template does not change portals already sent. The config is snapshotted onto each portal when it is created, so someone mid-checkout keeps the page they started on. The same is true of guides and the brand kit.

Layout blocks

layout is an ordered array. Every block needs a unique id you choose.

`type`	Purpose	Key fields
`header`	Renders the configured header.	—
`offerHero`	One offer, full width.	`offerId`, `badgeLabel`, `headline`, `tagline`
`offer`	One offer, standard card.	`offerId`, `badge`
`offerGrid`	Several offers in a grid.	`offerIds`, `columns` (`1` or `2`)
`bundle`	Offers sold together.	`offerIds`, `label`, `bundlePriceInCents`
`text`	Copy.	`body`, `variant` (`section` or `body`)
`trustStrip`	Reassurance row.	`items`
`spacer`	Vertical space.	`size` (`sm`, `md`, `lg`)
`image`	A picture.	`url`, `alt`, `aspectRatio`
`formInput`	Collect a value.	`name`, `label`, `required`, `inputType`
`paymentPlaceholder`	Where checkout renders.	`label`

trustStrip items are secure_checkout, free_cancellation, verified_business, and powered_by_stripe. Every offerId and offerIds entry has to be a real offer, so create offers first.

Building one

{
  "workspace_id": "ws_123",
  "name": "Arrival portal",
  "status": "draft",
  "branding": {
    "brand_color": "#1F6F5C",
    "accent_color": "#E8B44A",
    "theme": "light"
  },
  "header": {
    "business_name": "Seabright Rentals",
    "context_line": "Your stay starts soon",
    "hero_source": "listing",
    "show_trust_badge": true
  },
  "layout": [
    { "id": "b1", "type": "header" },
    {
      "id": "b2",
      "type": "offerHero",
      "offerId": "off_late_checkout",
      "headline": "Stay a little longer",
      "tagline": "Check out at 2 PM instead of 10 AM."
    },
    { "id": "b3", "type": "text", "variant": "section", "body": "Add to your stay" },
    {
      "id": "b4",
      "type": "offerGrid",
      "offerIds": ["off_airport_pickup", "off_midstay_clean"],
      "columns": 2
    },
    { "id": "b5", "type": "paymentPlaceholder" },
    {
      "id": "b6",
      "type": "trustStrip",
      "items": ["secure_checkout", "powered_by_stripe"]
    }
  ],
  "checkout": {
    "allow_cart": true,
    "payment_methods": ["card", "apple_pay"],
    "cta_label": "Confirm and pay"
  }
}

Colours are six-character hex, with or without the leading #.

The rest of the config

listing_data toggles property facts onto the page (address, wifi, parking, doorCode, checkInInstructions, houseRules, and friends), each an independent boolean under fields with an enabled master switch. after_payment sets what happens post-purchase (mode of stay or full_screen, plus message and show_receipt). confirmation_message controls the follow-up message. smart_lock enables lock integration.

Duplicating, archiving, deleting

duplicate_portal_template copies to a new draft, which is the safe way to revise an active portal. archive_portal_template and restore_portal_template are reversible. delete_portal_template is not: it requires confirm_name to match the template’s name exactly, only works when the template has no recorded sales, and deletes the portals created from it.

End to end

Building a working portal with a deposit on long stays:

Create the offers

create_portal_offer for each thing being sold. Keep the returned id values.

Create the verification rules

create_verification_rule for the deposit and the arrival details. Both land at the end of the list, enabled.

Fix the order

reorder_verification_rules with every rule, specific above general, so the long-stay deposit sits above any catch-all.

Build the template

create_portal_template with a layout referencing the offer IDs from step 1.

Activate

patch_portal_template with status: "active" and the template’s current expected_version.

A prompt that drives the whole thing:

In workspace ws_123, create a late checkout offer at $35 and an airport pickup
offer with sedan and van options. Then add a $500 security deposit rule for
stays of 7 nights or more, and an arrival details rule asking for phone and ETA
on every stay. Put the deposit above any existing catch-all deposit. Finally
build a draft template called "Arrival portal" with the late checkout as the
hero and the pickup in a grid below it.

Tool reference

Tool	Permission
`list_verification_rules`, `get_verification_rule`	View Upsells
`create_verification_rule`, `patch_verification_rule`, `delete_verification_rule`, `reorder_verification_rules`	Manage Upsells
`list_portal_offer_catalog`, `get_portal_offer`	View Upsells
`create_portal_offer`, `patch_portal_offer`, `archive_portal_offer`, `restore_portal_offer`	Manage Upsells
`list_portal_template_catalog`, `get_portal_template`	View Upsells
`create_portal_template`, `patch_portal_template`, `duplicate_portal_template`, `archive_portal_template`, `restore_portal_template`, `delete_portal_template`	Manage Upsells
`list_portal_guides`, `get_portal_guide`	View Upsells
`create_portal_guide`, `patch_portal_guide`, `duplicate_portal_guide`, `archive_portal_guide`, `restore_portal_guide`, `reorder_portal_guides`	Manage Upsells
`get_portal_brand_kit`, `patch_portal_brand_kit`	View / Manage Upsells

get_portal, update_portal, list_portal_offers, get_customer_portals, and get_checkin_status are runtime tools that serve a portal to a specific person, rather than configuration tools. They read and write one live portal, not the workspace setup described here.

Errors

Code	Cause
`forbidden`	Portals not enabled, or the token’s user lacks the permission.
`conflict`	`expected_updated_at` or `expected_version` is stale. Re-read and retry.
`invalid_input`	Config does not fit the step type, a validation rule failed, or a referenced ID does not exist.
`not_found`	The resource is not in this workspace.

Read the current value back before retrying a conflict. Both locks are checked against the stored record, so a blind retry with the same value fails the same way.

​Overview

Verification rules

Offers

Templates

​Before you start

​Verification rules

​Step types

​The rule that governs everything: one rule per slot

​Creating a rule

​Targeting

​Reordering

​Editing and deleting

​Portal offers

​Flat pricing

​Priced by option

​Pricing off the booking total

​Targeting and availability

​Archiving

​Portal templates

​Status and versioning

​Layout blocks

​Building one

​The rest of the config

​Duplicating, archiving, deleting

​End to end

​Tool reference

​Errors

Overview

Before you start

Verification rules

Step types

The rule that governs everything: one rule per slot

Creating a rule

Targeting

Reordering

Editing and deleting

Portal offers

Flat pricing

Priced by option

Pricing off the booking total

Targeting and availability

Archiving

Portal templates

Status and versioning

Layout blocks

Building one

The rest of the config

Duplicating, archiving, deleting

End to end

Tool reference

Errors