ChatBeds Network
Referrals between hotels when one is full, walks, monthly statements between hotels, shifts for network staff, and good guests' signed records. The hotel endpoints, the booking page's, and checking a signed record yourself.
The ChatBeds Network lets independent ChatBeds hotels help each other. A hotel joins after accepting the terms and chooses each part: referrals (send guests on when full and earn a fee), walks, shared staff and good guests (a signed stay record skips the card deposit). A hotel sees only the bookings it receives; the sender sees dates, amounts and fees, never the guest.
The fee is network-wide: 10% of the stay, owed by the receiving hotel to the sender once the guest has checked out and paid in full. Cancelled stays and no-shows owe nothing.
Every endpoint takes property_id as a query parameter and is called with a signed-in person's login (a Firebase ID
token), inside their role.
| Endpoint | Permission | What it does |
|---|---|---|
GET /api/v1/network | settings.manage | Membership, terms, fee, the hotel's review score and network hotels nearby |
POST /api/v1/network/join | settings.manage | Join: accepted_terms (the terms version shown) and the parts |
PUT /api/v1/network | settings.manage | Change the parts, min_rating, only and blocked (property ids) |
POST /api/v1/network/leave | settings.manage | Leave; open shifts are taken down |
GET /api/v1/network/referrals | reports.view | Guests sent (no guest data) and received (with the guest and booking) |
GET /api/v1/network/statements?month=YYYY-MM | reports.view | Per other hotel and currency: owed_to_you, you_owe, net, paid |
POST /api/v1/network/statements/{month}/{hotel_id}/paid?currency= | settings.manage | The hotel that is owed marks it received |
GET /api/v1/network/alternatives?arrival&departure&adults&children | reservations.view | Nearby network hotels with a room and their cheapest total |
POST /api/v1/network/walk/{reservation_id} | reservations.manage | Move a booked guest: to_property_id, optional room_type_id, pay_difference |
GET /api/v1/network/shifts | staff.manage | Shifts posted, who took them, ratings |
POST /api/v1/network/shifts | staff.manage | Post one: role, starts_at, ends_at, optional certificate, pay, note |
POST /api/v1/network/shifts/{id}/rate | staff.manage | stars 1–5 and a note |
POST /api/v1/network/shifts/{id}/cancel | staff.manage | Take an open shift down |
Join
/api/v1/network/joinsettings.managecurl -X POST "https://app.chatbeds.app/api/v1/network/join?property_id=6f1c3b2e-8a0d-4f5e-9b7a-2c3d4e5f6a7b" \
-H "Authorization: Bearer $FIREBASE_ID_TOKEN" -H "Content-Type: application/json" \
-d '{"accepted_terms": "1", "referrals": true, "staff": true, "good_guest": true, "min_rating": 4}'accepted_terms must be the terms.version that GET /api/v1/network returned; anything else is 400.
Who is shown
A hotel's alternatives are network hotels in the same city and country with referrals on, that the sender accepts
(not in its blocked, in its only list when it keeps one, rated at least min_rating out of 5 from its reviews) and
that don't block the sender. A hotel that hasn't joined is never shown.
The booking page
| Endpoint | What it does |
|---|---|
GET /public/v1/book/{property_id}/network?arrival&departure&adults&children | When this hotel is full: up to 3 nearby network hotels, cheapest first, each with url |
POST /public/v1/book/{property_id}/reservations | Takes network_ref: the nr parameter of that url, signed by ChatBeds |
{
"hotels": [
{
"hotel": {"id": "2b0c…", "name": "Lahore Inn", "city": "Peshawar", "rating": 4.4},
"room_type": "Deluxe",
"total": 200.0,
"currency": "PKR",
"url": "https://app.chatbeds.app/book?p=2b0c…&arrival=2026-11-14&departure=2026-11-16&adults=2&children=0&nr=…"
}
]
}The nr token names the sending hotel and lasts 2 days. A missing, changed or expired token books normally and records
no referral.
GET /public/v1/book/{property_id} has network: {"good_guest": true} when the hotel lets good guests skip the
deposit (else null).
Good guests
On POST /public/v1/book/{property_id}/reservations, guest.passport takes a good stay's record: its id (CBR-…), its
check link, or its signed copy (the JWT). When it is ChatBeds-signed and unchanged, valid, the guest's own (the booking's
phone or email), from a network hotel, and this hotel has good_guest on, a hotel that requires a card online accepts
payment: "HOTEL". The answer's passport says what happened:
{"ok": true, "from": "Pearl Hotel", "deposit_skipped": true}{"ok": false, "error": "This record isn't signed by ChatBeds: it was changed or made elsewhere."}A Guest Memory Passport given in the same field is handled as before (its preferences are imported).
Checking a signed record yourself
Records are W3C Verifiable Credentials signed with Ed25519 (alg: EdDSA) as a JWT. Anyone can check one:
GET /public/v1/records/keys: ChatBeds' public key as a JWK set (kidin the JWT header).GET /public/v1/records/check/{id}: the record's status (valid,expired,withdrawn), its facts andjwt(null unless valid). Never the holder's phone or email: those are in the credential only as salted SHA-256 hashes.
Verify the JWT's signature with the key, then check exp and that /records/check/{sub} still says valid (a holder
can withdraw a record at any time).
Shifts on WhatsApp
People join from their own work record page (PUT /public/v1/records/mine/{token}/network with join, phone (the
number on the record), city, share_certificates, share_ratings). A posted shift goes to each eligible person from
the hotel's WhatsApp number, by the cb_network_shift template when approved. The first to reply TAKE <code> has it.
Building something?