StayNTouch logo

StayNTouch Integration

Connects via OAuth 2.0 client credentials. Tokens are refreshed automatically. Supports the fullest reservation lifecycle of any provider. StayNTouch official site ↗

Supported features

FeatureSupportedNotes
Hotel availability✓Requires hotel ID, check-in/out, adults, children
Room types✓
Room rates✓
List / get reservations✓
Create reservation✓Three-step flow with guest lookup
Payment link✓Fetched automatically after reservation creation
Rate plans—

Setup steps

  1. Request OAuth credentials from StayNTouch

    Contact your StayNTouch account manager or open a support ticket to request a Partner API client ID and client secret. StayNTouch uses OAuth 2.0 client credentials — there is no self-serve portal for generating these.

    StayNTouch operates on multiple regional data centres. Ask which apiEnv and authEnv values correspond to your property — choosing the wrong region returns authentication errors even with valid credentials.

  2. Identify your hotel ID

    Your hotel ID is a string identifier assigned by StayNTouch. It appears in the StayNTouch admin portal under Hotel Setup → Property Details, or can be obtained from your account manager. You need this for the hotelConfig array.

  3. Choose your regional environment

    Select the correct region pair for your property:

    RegionapiEnvauthEnv
    US (default)usus
    US1us1us
    US2us2us
    EUeu1eu
    UAT / sandboxuatuat

  4. Enter the credentials in the business console

    Open the business console, select the client, and go to Settings → Integrations. Choose Add integration, type Property Management System, provider StayNTouch, and fill in:

    • Client ID and Client Secret — from step 1
    • Auth Environment and API Environment — the region pair from step 3, chosen from the dropdowns
    • Hotel Name and Hotel ID — from step 2

  5. Save and test

    Select the tool access and click Save. OAuth tokens are fetched and cached automatically — no manual token management needed. Ask the concierge for a room on a near-future date; an authentication error means the two environments do not match.

Available tools

10 tools are available for StayNTouch. The concierge calls them on a guest's behalf during a conversation; which are enabled is set per property, so you only turn on what you want it to be able to do.

Enabled by default (3)

On as soon as the integration is connected, with nothing else to configure.

ToolWhat it does
stayntouch_get_availabilityCheck room availability at the hotel for a stay window. This is the PRIMARY availability tool — call it first for any 'do you have rooms...' question, and reuse the availability response already retrieved in this conversation instead of calling again for the same dates and party. Dates are ISO YYYY-MM-DD. An empty result means NO availability for those dates — that is a real answer, not an error: do not retry, and do not try other tools to find rooms; offer the hotel's booking site or a staff handoff instead. The numeric rate_id and room_type_id values in this response are the ONLY valid source of ids for stayntouch_get_room_rates and stayntouch_create_reservation. Unsupported queries to politely DECLINE rather than approximate: searching a date range for the cheapest stay, 'when is your next available date?', and minimum-stay (min-stay) rule enforcement — this API only answers fixed-date availability.
stayntouch_get_room_ratesGet the nightly rates for ONE rate + room type over a stay window. Only call this after availability has been confirmed with stayntouch_get_availability, and only with the numeric rate_id and room_type_id extracted from that availability response — NEVER invent or guess these ids. Dates are ISO YYYY-MM-DD. Quote the guest the TOTAL for the stay, not a per-night figure.
stayntouch_get_room_typesList the hotel's room types (names, descriptions, occupancy) for a stay window. Use this to answer 'what kinds of rooms do you have?' or to describe room options — for live availability use stayntouch_get_availability, and for prices use stayntouch_get_room_rates. Dates are ISO YYYY-MM-DD.

Available on request (7)

Off by default. Ask Maison to enable any of these for your property — several change data in your StayNTouch account, so they are opt-in rather than assumed.

ToolWhat it does
stayntouch_create_reservationCreate a NEW reservation. Booking flow: start with stayntouch_get_guest (email-first guest recognition) to decide whether to pass a guest_id. BEFORE calling: the guest MUST explicitly confirm a booking summary showing the TOTAL stay price (not per-night figures) — never create without that confirmation. stay_dates MUST contain EXACTLY one entry per night of the stay (a 3-night stay has 3 entries), each with date (ISO YYYY-MM-DD), rate_id, room_type_id, adults, and children; rate_id and room_type_id are numbers and live ONLY inside each stay_dates entry — never at the top level of the request. NEVER invent or guess rate_id or room_type_id — take them from the stayntouch_get_availability response. guests: exactly one entry with is_primary true — pass id (guest_id) when stayntouch_get_guest matched the guest's card, otherwise first_name, last_name, and email (phone optional); the email is required for the confirmation letter. Put special requests in notes. NEVER retry this call after a timeout or ambiguous failure — the booking may already exist and retrying can double-book; look it up (e.g. stayntouch_list_reservations) or hand off to staff instead. AFTER a successful create: immediately call stayntouch_get_reservation_by_id with the returned internal id to obtain the confirmation_number; give the guest ONLY the confirmation_number, NEVER the internal id. Then call stayntouch_send_confirm_letter with the booker's email — this hotel SENDS its native confirmation email (the one provider where Maison does) — and optionally stayntouch_get_pay_link for a payment link.
stayntouch_get_guestLook up an existing guest card by email — the FIRST step of the StayNTouch booking flow. Ask the guest for their email FIRST, before anything else in the booking flow, then call this. On a hit: greet them 'Welcome back, [first_name]!' and compare the returned first_name and last_name against what the guest states. Phone is ONLY an optional tiebreaker: treat it as a mismatch only when BOTH sides have a phone number and they differ; if either side lacks a phone, ignore it entirely. If the names match (and the phone does not contradict), reuse the card by passing the returned id as guest_id in the stayntouch_create_reservation guests entry. If the names do NOT match, do NOT reuse the card — omit guest_id and a new guest card will be created. If no guest is found, proceed normally without guest_id.
stayntouch_get_pay_linkGet a payment link for a reservation so the guest can pay online. The reservation_id in the path is the INTERNAL database id (from the create response, or bills[0].reservation_id on a reservation's bills) — not the confirmation number. Optional final step after creating a booking; if it fails, the booking is unaffected — do not retry, just omit the link.
stayntouch_get_reservationLook up one reservation by its internal reservation id (query form) and return its confirmation_number, status, stay dates, per-night details, and totals. The reservation_id is the INTERNAL database id (e.g. from a create response) — it is never shown to the guest; always quote the confirmation_number instead.
stayntouch_get_reservation_by_idFetch one reservation by its internal database id (path form). Call this immediately after stayntouch_create_reservation to obtain the guest-facing confirmation_number. Give the guest ONLY the confirmation_number — NEVER the internal id. If this lookup fails or returns no confirmation_number, the booking STILL EXISTS: tell the guest their booking is created and the confirmation number will follow — do NOT re-attempt or re-create the reservation.
stayntouch_list_reservationsOPERATOR-GRADE: never use in guest conversations unless explicitly instructed. List the hotel's reservations as an id-free summary (confirmation number, status, dates, party, primary guest name). Use it to review bookings or to cross-reference a booking after an ambiguous create failure.
stayntouch_send_confirm_letterSend the hotel's NATIVE confirmation email for a reservation to the listed addresses. StayNTouch is the one provider where Maison deliberately triggers the PMS's own guest email — call this right after stayntouch_get_reservation_by_id in the booking flow, with the booker's email. This step is best-effort: a failure must not block, undo, or retry the booking — the reservation stands either way.

Not yet certified (19)

Built and working against the StayNTouch API, but Maison is not yet certified with StayNTouch to use them in production, so they cannot be enabled today. Listed so you can see what is coming rather than discover the gap when you ask for it.

ToolWhat it does
stayntouch_add_reservation_notesAdd one or more notes to an EXISTING reservation (special requests, preferences the guest states in conversation). The reservation_id is the INTERNAL database id — never shown to the guest. Check stayntouch_get_reservation_notes first to avoid duplicates. Notes cannot be edited or deleted through this integration, so keep each note short and factual.
stayntouch_assign_roomOPERATOR-GRADE: never use in guest conversations unless explicitly instructed. Assign a specific room to a reservation. The reservation_id is the INTERNAL database id; room_id is the numeric room id from stayntouch_list_rooms — NEVER invent it, and pick a room whose room_type_id matches the reservation. Do not retry after a timeout — the assignment may already be applied; verify first.
stayntouch_cancel_reservationCancel an EXISTING reservation. This cannot be undone — BEFORE calling, the guest MUST explicitly confirm they want to cancel THIS specific stay (state the confirmation_number and dates back to them). The reservation_id is the INTERNAL database id (from stayntouch_search_reservations or a create response) — never shown to the guest. Set send_cancellation_email true when the guest wants StayNTouch's own cancellation email; you can also send the hotel's cancellation letter afterwards with stayntouch_send_cancel_letter. A response with status false means the cancellation did NOT happen — relay the reason and offer a staff handoff. NEVER retry after a timeout or ambiguous failure — the reservation may already be cancelled; check with stayntouch_get_reservation_by_id instead.
stayntouch_check_inOPERATOR-GRADE: never use in guest conversations unless explicitly instructed. Check in a reservation at the front desk. The reservation_id is the INTERNAL database id. Set queue_when_not_ready true to queue the check-in when the room is not ready yet. Returns the assigned room (number, housekeeping status, floor) — relay the room number to the operator. Do not retry after a timeout or ambiguous failure — the reservation may already be checked in; verify its status first.
stayntouch_check_outOPERATOR-GRADE: never use in guest conversations unless explicitly instructed. Check out a reservation. The reservation_id is the INTERNAL database id. Review the balance with stayntouch_get_reservation_bills before checking out. Do not retry after a timeout or ambiguous failure — the reservation may already be checked out; verify its status first.
stayntouch_create_guestCreate a NEW guest card (guest profile) for the hotel chain. Use it only when stayntouch_get_guest found no existing card for the guest's email — creating duplicates pollutes the hotel's guest database. Only last_name is required, but always include first_name and email when the guest provided them. Use the returned id as the guest_id in later calls. NEVER retry after a timeout — the card may already exist; look it up with stayntouch_get_guest instead.
stayntouch_get_guest_by_idRead one guest card by its internal guest id (e.g. the guest_id from stayntouch_search_reservations or the id from stayntouch_get_guest). Returns the guest's name, title, email, phone numbers, language, and guest notes. The id is INTERNAL — never show it to the guest. For finding a guest by email use stayntouch_get_guest instead.
stayntouch_get_queue_detailsCheck where a reservation stands in the check-in queue for its room type: its queue position, how many reservations are queued, and how many rooms are currently available. Useful when a guest asks 'is my room ready yet?'. The reservation_id is the INTERNAL database id — never shown to the guest.
stayntouch_get_reservation_billsRead the detailed bills (folios) of a reservation — every charge and payment posted, grouped by bill, with charge group, amount, currency, and date. Use it to answer 'what's on my bill?' or 'what do I owe?'. The reservation_id is the INTERNAL database id — never shown to the guest. Quote amounts with their currency_code. Card numbers are never returned by this tool.
stayntouch_get_reservation_depositsRead the deposit details of a reservation: the deposit policy name, amount already paid, amount still owed, and the due dates with their amounts. Use it for 'have I paid my deposit?' / 'when is my deposit due?'. The reservation_id is the INTERNAL database id — never shown to the guest.
stayntouch_get_reservation_notesList the notes recorded on a reservation (special requests, staff notes), paginated. The reservation_id is the INTERNAL database id — never shown to the guest. Use this to check what has already been noted before adding a duplicate with stayntouch_add_reservation_notes.
stayntouch_get_reservation_revenueRead the revenue posted on a reservation grouped by date and charge type (ROOM, TAX, F & B, FEES, ADDON, …). Use it for a per-night cost breakdown of a stay; for the itemised folio use stayntouch_get_reservation_bills instead. The reservation_id is the INTERNAL database id — never shown to the guest. Quote amounts with their currency_code.
stayntouch_get_room_service_statusOPERATOR-GRADE: never use in guest conversations unless explicitly instructed. Read one room's service status (IN_SERVICE / OUT_OF_ORDER / OUT_OF_SERVICE / OUT_OF_INVENTORY) per date over a date range starting today or later (maximum 90 days). room_id comes from stayntouch_list_rooms. Dates are ISO YYYY-MM-DD. Paginated (per_page maximum 50).
stayntouch_list_roomsOPERATOR-GRADE: never use in guest conversations unless explicitly instructed. List the hotel's rooms with their live housekeeping status (CLEAN / INSPECTED / DIRTY / PICKUP), service status (IN_SERVICE / OUT_OF_ORDER / OUT_OF_SERVICE / OUT_OF_INVENTORY), occupancy, and floor. The returned id is the room_id needed by stayntouch_assign_room. Paginated (per_page maximum 50).
stayntouch_modify_reservationUpdate an EXISTING reservation — change its dates, nightly rate/room-type lines, or occupancy. The reservation_id is the INTERNAL database id (from stayntouch_search_reservations or a create response) — never shown to the guest; always quote the confirmation_number instead. Dates are ISO YYYY-MM-DD; times are HH:MM. arrival_date and departure_date are always required and must reflect the FULL post-change stay. When changing dates, room type, rate, or party size, send stay_dates with EXACTLY one entry per night of the new stay (departure date excluded), each carrying the numeric rate_id and room_type_id — NEVER invent or guess these ids; take them from a fresh stayntouch_get_availability response for the new dates. BEFORE calling: the guest MUST explicitly confirm a summary of the change including the new TOTAL stay price. NEVER retry this call after a timeout or ambiguous failure — the change may already be applied; call stayntouch_get_reservation_by_id to see the current state instead. AFTER a successful update, re-read the reservation with stayntouch_get_reservation_by_id and confirm the new details to the guest (give them ONLY the confirmation_number, NEVER the internal id).
stayntouch_pre_check_inPre-check-in a reservation — record the guest's expected arrival time so the hotel can prepare their room (the guest-facing online check-in step; it does NOT hand over the room — staff complete the actual check-in). The reservation_id is the INTERNAL database id — never shown to the guest. arrival_time must be in HH:MM AM/PM form (e.g. '02:30 PM'). If the response includes a queue_position, tell the guest their room is being prepared and where they are in the queue. Do not retry after a timeout — check the reservation state instead.
stayntouch_search_reservationsSearch the hotel's reservations and get a compact summary per match — the way to FIND a guest's reservation when you only have their name, email, city, or phone number. query matches across guest city, email, first name, and last name (minimum 2 characters); mobile_number / home_phone match on at least 4 consecutive digits. Filter by status and by date (date with date_operator, or a from_date/to_date range of at most 31 days combined with date_filter — never combine the range with date or date_operator). Dates are ISO YYYY-MM-DD. The returned id and guest_id are INTERNAL database ids for follow-up calls (stayntouch_get_reservation_by_id, stayntouch_modify_reservation, stayntouch_update_guest, …) — NEVER show these internal ids to the guest; always quote the confirmation_number.
stayntouch_send_cancel_letterSend the hotel's cancellation letter for a cancelled reservation to the primary guest and/or the listed email addresses. Call it after stayntouch_cancel_reservation when the guest wants written confirmation of the cancellation; omit emails to send to the primary guest on file. This step is best-effort: a failure must not block or retry anything — the cancellation stands either way.
stayntouch_update_guestUpdate an EXISTING guest card — correct or complete the guest's name, title, email, phone numbers, language, or add guest notes. First resolve the card with stayntouch_get_guest (by email) or stayntouch_get_guest_by_id and confirm with the guest exactly what should change — NEVER guess a guest_id and never overwrite fields the guest did not ask to change (send only the fields being changed). The guest_id is INTERNAL — never show it to the guest. NEVER retry after a timeout — the update may already be applied; re-read the card instead.