REST API reference.

Authentication

The Guest Talk API authenticates every request with a Bearer token issued from the operator UI under Settings → Integrations → API tokens. A token is scoped to exactly one tenant and to a subset of resource permissions — read-only, read-write, or full — and can be rotated at any time without downtime because both the old and the new value remain valid for a 15-minute overlap window. Tokens do not expire on a clock, but a token that has not been used for six months is automatically revoked.

Authorization: Bearer tgk_live_a7f9b2c1d4e5f6a7b8c9d0e1f2a3b4c5
Accept: application/json
User-Agent: my-integration/1.4.2

Send the token in the Authorization header on every request; there is no session cookie, no CSRF token, and no OAuth flow for machine integrations. If you need per-staff-member OAuth for a UI-facing product that acts on behalf of individual hotel employees, see the integrations overview — that flow is documented separately from the machine token flow described here.

Base URL and versioning

Production sits at https://api.talk.mindbery.org/v1. Sandbox sits at https://sandbox.talk.mindbery.org/v1. Both environments accept the same routes with the same shapes; the sandbox is a full-fidelity clone with synthetic data. The v1 in the path is the major version — Talkguest guarantees backwards-compatible additions within a major version and only breaks contracts on a version bump, which is announced at least twelve months in advance and released alongside the previous version so no integration is forced to migrate on a hard deadline.

Endpoint index

Reservations

The reservation resource is the centre of gravity of the platform. Every reservation carries a stay window, a rate plan, a rate quote, a room assignment (which may be soft until check-in), a guest profile pointer, a booking channel and a state — tentative, confirmed, checked_in, checked_out, or cancelled. A reservation exists inside a folio; if the folio is not passed at create time the platform creates one implicitly.

GET /v1/reservations?arrival_from=2026-08-01&arrival_to=2026-08-07&status=confirmed
Host: api.talk.mindbery.org

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": "res_01HYQ8XN2K9AB4C7",
      "status": "confirmed",
      "channel": "booking_com",
      "arrival": "2026-08-03",
      "departure": "2026-08-06",
      "nights": 3,
      "adults": 2,
      "children": 0,
      "guest_id": "gst_01HYQ8XN2K9AB4C6",
      "rate_plan_id": "rp_flex_bar",
      "room_type_id": "rt_dbl_seaview",
      "room_assignment": "soft",
      "quote": { "currency": "EUR", "subtotal": "462.00", "tax": "27.72", "total": "489.72" },
      "folio_id": "fol_01HYQ8XN2K9AB4CA",
      "created_at": "2026-07-19T14:22:41Z"
    }
  ],
  "next_cursor": "eyJvIjoxMDAsImxpbSI6MTAwfQ=="
}

Creating a reservation from an external system is a POST to /reservations with a minimum of arrival, departure, room type, rate plan and a guest reference. The guest reference can be an existing guest_id or a nested guest object that the platform will materialise into a profile atomically with the reservation. If the room type has no availability for the requested window the platform returns 409 Conflict with error code TG-3001 (overbooking) documented on the error codes page.

POST /v1/reservations
Content-Type: application/json

{
  "arrival": "2026-08-14",
  "departure": "2026-08-17",
  "room_type_id": "rt_dbl_seaview",
  "rate_plan_id": "rp_flex_bar",
  "adults": 2,
  "guest": {
    "first_name": "Ana",
    "last_name": "Martins",
    "email": "ana.martins@example.pt",
    "nationality": "PT"
  },
  "channel": "direct"
}

Guests

A guest profile carries the identifying information required by Portuguese law (SEF/AL) — full name, nationality, document type and number, place and date of birth — plus the operational attributes the property uses to personalise the stay: language, dietary restrictions, arrival preferences, past-stay notes. Every guest carries a stable gst_ id that survives merges; if you merge two profiles that the platform later determines are the same person, the surviving id keeps every reservation pointer and the merged id is retained as an alias so external systems that cached the old id still resolve.

GET /v1/guests/gst_01HYQ8XN2K9AB4C6

{
  "id": "gst_01HYQ8XN2K9AB4C6",
  "first_name": "Ana",
  "last_name": "Martins",
  "email": "ana.martins@example.pt",
  "phone": "+351912345678",
  "nationality": "PT",
  "document": { "type": "cc", "number": "12345678", "issue_country": "PT" },
  "language": "pt-PT",
  "past_stays": 3,
  "lifetime_value": { "currency": "EUR", "amount": "1284.50" }
}

Rate plans

Rate plans describe the commercial policy attached to a stay — the pricing formula, the cancellation window, the payment schedule, the channel restrictions. Talkguest supports a fixed-rate plan, a BAR (best available rate) plan that references a daily rate table, a package plan that bundles ancillary services, and a corporate plan bound to a company account with a negotiated discount. A rate plan is retrievable by id and listable per property; you cannot mutate rate plans through the API because their history matters for revenue attribution — create a new plan and deprecate the old one instead.

Availability

The availability endpoint returns rooms available and rooms sold per room type per date across a window. It is the endpoint a channel manager reads to know what to publish outward, and the endpoint an internal dashboard reads to build the tape chart. Availability writes go through the same endpoint with a POST; the payload is a list of {date, room_type_id, available} tuples that Talkguest applies atomically per date.

GET /v1/availability?from=2026-08-01&to=2026-08-07&room_type_id=rt_dbl_seaview

{
  "data": [
    { "date": "2026-08-01", "room_type_id": "rt_dbl_seaview", "available": 4, "sold": 8, "total": 12 },
    { "date": "2026-08-02", "room_type_id": "rt_dbl_seaview", "available": 2, "sold": 10, "total": 12 }
  ]
}

Folios

A folio is the running account attached to a stay. It accumulates room charges, ancillary charges, taxes, discounts and payments; at check-out the folio is either paid, transferred, or written off. The API supports posting a charge, posting a payment, splitting a folio into two, and merging two folios into one. Every folio movement carries an idempotency key so that repeated posts from a retry loop do not double-count.

POST /v1/folios/fol_01HYQ8XN2K9AB4CA/charges
Idempotency-Key: e9f2c1b4-8a7d-4e6c-9b3a-1d2e5f8a9c0b

{
  "amount": { "currency": "EUR", "amount": "18.50" },
  "code": "minibar",
  "description": "Minibar consumption",
  "posted_by": "usr_01HYQ8XN2K9AB4CC"
}

Messages

The messaging resource is the two-way conversation with the guest. Inbound messages arrive over WhatsApp, email, SMS or the direct-booking web widget; outbound messages go back over the same channel unless the guest has explicitly changed the preference. Every message carries the resolved reservation_id and guest_id plus the raw payload from the underlying transport. Sending a message is a POST with the target reservation, a body, and an optional template id if you want the platform to interpolate variables at send time.

Reports

Canned reports are exposed at /reports/{name} with parameters as query string. Common report names include daily-arrivals, occupancy, revenue-by-channel, rate-mix and housekeeping-status. Every report returns a JSON body suitable for a dashboard, and every report can be requested as CSV by setting the Accept header to text/csv. Reports are computed on a five-minute freshness cadence and cached; if you need real-time numbers, query the underlying resources.

Pagination and filtering

List endpoints paginate with cursor pagination. The response carries next_cursor when more pages exist; pass it as ?cursor=… on the next request. Do not construct cursors yourself; they are opaque. Filtering follows a query-string convention: ?status=confirmed, ?arrival_from=2026-08-01, ?channel=direct,booking_com. Multi-value filters accept comma-separated lists.

Errors and rate limits

Every non-2xx response carries a JSON body with a code, a message and a request_id. The code is a stable Talkguest-specific string documented on the error codes page; the request id is the value you share with support to have a specific request looked at. Rate-limit responses carry Retry-After and the X-RateLimit-* header family documented on the rate limits page.

Next steps

Once basic reads work, subscribe to webhooks so you can stop polling. For architecture support or scoping conversations with the integrations team, use the contact page. If you do not yet have a sandbox tenant, request access and one will be provisioned for you.