---
name: "maison-integrations"
description: "Connect third-party systems to a hotel in one call: browse the provider catalogue, list a hotel's integrations (credentials masked), add or update an integration with credentials, config and tool audiences, enable, disable or remove it, verify a config value against the provider, list provider properties (rezStream, Mews, ResNexus), email a hotel's account holder the consent link for rezStream or STS Cloud, and list the PMS rate plans. Use when onboarding a hotel's PMS, payment gateway or booking system, or when a booking tool stops working. Tools: add_integration, check_integration_config, disable_integration, enable_integration, list_client_integrations, list_integration_catalog, list_integration_properties, list_pms_rate_plans, remove_integration, send_integration_connect_link."
license: "Proprietary. Use with a Maison API key under the Maison terms of service."
metadata:
  author: "maison-labs"
  version: "1.0.0"
  category: "integrations"
  api-base: "https://maison-labs.com"
  openapi: "https://maison-labs.com/api/v1/openapi.json"
  docs: "https://docs.maison-labs.com/skills/maison-integrations/"
---

# Maison — Integrations (PMS, payments, events)

Connect third-party systems to a hotel in one call: browse the provider catalogue, list a hotel's integrations (credentials masked), add or update an integration with credentials, config and tool audiences, enable, disable or remove it, verify a config value against the provider, list provider properties (rezStream, Mews, ResNexus), email a hotel's account holder the consent link for rezStream or STS Cloud, and list the PMS rate plans. Use when onboarding a hotel's PMS, payment gateway or booking system, or when a booking tool stops working.

Part of the Maison public API. Read the `maison-public-api` skill first for authentication, discovery and transport details (`https://docs.maison-labs.com/skills/maison-public-api/SKILL.md`).

## When to use

- Find the right provider and its required fields — `list_integration_catalog`.
- Connect or update — `add_integration` (idempotent upsert).
- Check why a provider call fails — `check_integration_config`, `list_integration_properties`.
- Connect rezStream or STS Cloud — `add_integration` with the account holder's `emailId`, then `send_integration_connect_link`.
- Pick a rate plan for a booking link or offer — `list_pms_rate_plans`.

## Before you start

1. Send `x-api-key: <key>` on every call; the key only reaches `/api/v1`.
2. `GET /api/v1/tools` (or MCP `tools/list`) returns the tools THIS key may run — if a tool below is missing there, you lack a grant; do not retry it.
3. Client-scoped tools take `clientId` (a hotel id). `whoami` lists the ids you can act on.

## Tools

| Tool | What it does | REST | Needs |
| --- | --- | --- | --- |
| `add_integration` | Create or update a hotel's integration: creates a new integration row for the provider, or replaces an existing one's credentials, config, and tool audiences. | `PUT /api/v1/client/{clientId}/integration/{provider}` | update-client WRITE (client); plan: `update-client` |
| `check_integration_config` | Validates one operator-entered config value against the provider before it can silently break a guest conversation. | `GET /api/v1/client/{clientId}/integration/{provider}/configcheck` | update-client READ (client); plan: `update-client`; read-only |
| `disable_integration` | Pauses an integration — config and credentials are preserved but the integration is excluded from tool delivery at once, until re-enabled. | `POST /api/v1/client/{clientId}/integration/{provider}/disable` | update-client WRITE (client); plan: `update-client`; destructive |
| `enable_integration` | Re-enables a previously disabled integration — credentials and config are restored exactly as they were and its tools are served again at once. | `POST /api/v1/client/{clientId}/integration/{provider}/enable` | update-client WRITE (client); plan: `update-client` |
| `list_client_integrations` | Returns all active integrations for a hotel with credentials MASKED (last 4 characters only — never decrypted). | `GET /api/v1/client/{clientId}/integrations` | update-client READ (client); plan: `update-client`; read-only |
| `list_integration_catalog` | Returns the full integration provider catalog grouped by type (pms, bookingengine, payments, …), including credential/config fields and available tools for each provider, plus announced coming-soon placeholders. | `GET /api/v1/integrations/catalog` | clients READ (any); read-only |
| `list_integration_properties` | Returns the properties (rezStream), bookable services (Mews) or businesses (ResNexus) of the connected account, as `properties: [{ id, name, timezone, currency, address, bookablePeriod? | `GET /api/v1/client/{clientId}/integration/{provider}/properties` | update-client READ (client); plan: `update-client`; read-only |
| `list_pms_rate_plans` | Returns the rate plans of the hotel's connected PMS (the provider's own response shape), e.g. | `GET /api/v1/client/{clientId}/pms/rateplans` | hotel-config READ (client); plan: `hotel-config`; read-only |
| `remove_integration` | Soft-deletes the active integration row and wipes all stored credentials and tokens; for `stripe` it also deletes the hotel's Stripe webhook endpoint (best-effort). | `DELETE /api/v1/client/{clientId}/integration/{provider}` | update-client WRITE (client); plan: `update-client`; destructive |
| `send_integration_connect_link` | Emails the hotel's own account holder a one-time link to grant Maison access to their rezStream or STS Cloud account — the only way these integrations connect, because consent must come from the hotel. | `POST /api/v1/client/{clientId}/integration/{provider}/connectlink` | update-client EXECUTE (client); plan: `update-client` |

Full input fields for every tool: [references/tools.md](references/tools.md).

## Recommended workflows

### Connect a PMS

1. `list_integration_catalog` → read the provider's `credentialFields`, `configFields` and tools.
2. `add_integration` with `credentials` and `config` exactly as the catalogue names them; set `toolAudiences` to control which tools guests may use.
3. For rezStream / STS Cloud: `send_integration_connect_link`; the hotel's account holder approves in their browser and the integration turns Connected (poll `list_client_integrations`).
4. `list_integration_properties` (rezstream/mews/resnexus) to pick the property/service/business id when the provider has several; it also refreshes the stored name of the selected one. Mews: `refresh: true` re-syncs the booking-engine configuration.
5. `check_integration_config` for fields the catalogue marks as verifiable, then `enable_integration`.

## Tips

- Only one PMS-type integration may be active per hotel; `add_integration` answers 409 when another is active.
- Credentials are never returned; `list_client_integrations` shows masked values and connection state.
- Stripe: `add_integration` with `credentials.secretKey` creates the hotel's Stripe webhook endpoint in the same call; a refused key is 422 `stripe_key_invalid` and nothing is saved. `remove_integration` deletes the endpoint.
- `disable_integration` / `enable_integration` take effect at once on the instance that served the call; others follow within a minute.

## Pitfalls

- rezStream and STS Cloud connect only when the hotel's own account holder approves: `send_integration_connect_link` emails them (409 until `emailId` — and for STS Cloud the OAuth Client Secret — is saved; 503 where the flow is not configured). Each call issues a new link.
- Never log or echo credentials back to the user.

## Calling conventions

Same tool, three transports — pick whichever your runtime already speaks. Always send `x-api-key`.

```bash
# REST
curl -X PUT "https://maison-labs.com/api/v1/client/<clientId>/integration/<provider>" -H "x-api-key: $MAISON_API_KEY" -H "content-type: application/json" -d '{}'
```

```json
// MCP (https://maison-labs.com/mcp, Streamable HTTP): tools/call
{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "add_integration", "arguments": {} } }
```

```json
// A2A (https://maison-labs.com/a2a): tasks/send with a data part
{ "jsonrpc": "2.0", "id": 1, "method": "tasks/send", "params": { "message": { "role": "user", "parts": [{ "type": "data", "data": { "tool": "add_integration", "input": {} } }] } } }
```

Errors are the same everywhere: `401` no/invalid key; `403 forbidden` with `details.missing` (the grants you lack — fall back to the composite's parts or stop); `403 not_entitled` (the hotel's plan lacks the feature); `404`, `409`, `413 too_large`, `503`. Inputs that fail validation return `400 invalid_input` with the Zod issues — fix and retry once.