In short: any host can create an API credential with Write access at Profile → API Credentials, then create properties, push and update bookings, and control their BetterSTR TVs over HTTPS. There is an interactive console at api.betterstr.com/user-api/docs where you can try every call against your own account before writing a line of code.
Who this is for
Most BetterSTR hosts never think about an API. They connect Hostaway, Guesty, Mews, Lodgify or one of the other PMSs we support and bookings flow in by themselves. But three groups kept asking for something else:
- Hosts on a PMS we cannot connect to. Some booking systems have no partner API, or charge for access. Until now the only options were adding bookings by hand or using an iCal feed, which has no guest names or contact details.
- Small hotels and apartment operators with their own software. A spreadsheet-driven booking sheet, a custom reservation system, a channel manager with a webhook. They can already talk HTTP; they just needed somewhere to send it.
- Developers building for a client. Agencies who want to wire a hotel’s booking engine straight into the in-room TV and guidebook without the hotel changing anything else.
Until now all of them needed us to set up a partner integration on their behalf. From today they can do it themselves, in an afternoon, with a key they control.
What you can do
| Area | With a write key you can |
|---|---|
| Properties | Create, update and delete the properties you manage without a PMS: address, timezone, check-in and check-out times, capacity, picture, tags. |
| Bookings | Push a booking with the guest’s name, dates, contact details and door code. Update it, cancel it, or send up to 50 at a time for a first import. |
| TVs | List your BetterSTR TVs, check power state, switch them on or off, put a message on the screen, change settings. |
| Everything that was already there | Guidebook entries, tags, map locations, SMS to guests, payment links, the WiFi guest marketing list. |
Bookings that come from a connected PMS stay read-only, because the PMS is their source of truth. The write calls only touch properties you added yourself, so a key can never scramble a Hostaway or Guesty sync.
Step 1: create a key with Write access
Log in, open Profile → API Credentials, click Create and tick Write access. You get a client_id starting with bsc_ and a client_secret starting with bss_. The secret is shown once, so copy it somewhere safe. Keys without Write access are read-only, and keys you created before today stay read-only until you create a new one.
Every request uses HTTP Basic auth with those two values. In the examples below we use placeholders; put your own in.
Step 2: find your property
curl -u "bsc_your_client_id:bss_your_client_secret" \
https://api.betterstr.com/user-api/v1/properties{"data":{"properties":[{
"uuid":"4f0c9a2e-6b1d-4c8e-9f3a-2d7e8b1c5a60",
"name":"Harbour View Apartment",
"display_address":"12 Quay Street, Auckland, 1010, New Zealand",
"city":"Auckland","country":"NZ",
"timezone_iana":"Pacific/Auckland",
"guide_url":"https://gb.betterstr.com/26/g/4f0c9a2e-6b1d-4c8e-9f3a-2d7e8b1c5a60"
}],"total":1}}The uuid is what every other call uses. If you have no property yet, add one in the dashboard, or create it through the API if your account is on the flat-rate Premium plan (more on that below). Note timezone_iana: booking times you send are read in that zone, with daylight saving handled for you.
Step 3: push a booking
reference is your own booking number. Send the same reference again and the booking is updated rather than duplicated, so a nightly re-sync of your whole calendar is safe.
curl -u "bsc_your_client_id:bss_your_client_secret" \
-X POST https://api.betterstr.com/user-api/v1/reservations \
-H "Content-Type: application/json" \
-d '{
"property_uuid": "4f0c9a2e-6b1d-4c8e-9f3a-2d7e8b1c5a60",
"reference": "BK-1001",
"first_name": "Ana", "last_name": "Silva",
"email": "ana@example.com", "phone": "+64211234567",
"check_in": "2026-12-20 15:00", "check_out": "2026-12-23 10:00",
"guests": 2, "door_code": "4821",
"total_amount": 540, "currency": "NZD"
}'HTTP 201
{"data":{"reservation":{
"id":"manual_u12345_bk-1001",
"reservation_code":"BK-1001",
"status":"accepted",
"guide_url":"https://gb.betterstr.com/26/g/r/manual_u12345_bk-1001",
"arrival_date":"2026-12-20 15:00:00","departure_date":"2026-12-23 10:00:00",
"nights":3,"guest_name":"Ana Silva","guests":2,"door_code":"4821"
},"created":true,"notified":true}}That one call does everything a PMS sync does. Ana gets her personal guidebook link (guide_url), your welcome automations send it by SMS or email if you have set them up, the TV shows her name during her stay, and the door code appears in her guide at the time you have chosen. When you import old bookings, add "notify": false so nobody gets a welcome message for a stay that already happened.
Update or cancel
curl -u "bsc_your_client_id:bss_your_client_secret" \
-X PATCH https://api.betterstr.com/user-api/v1/reservations/BK-1001 \
-H "Content-Type: application/json" \
-d '{"guests": 3, "door_code": "5678"}'
curl -u "bsc_your_client_id:bss_your_client_secret" \
-X POST https://api.betterstr.com/user-api/v1/reservations/BK-1001/cancelFirst import, up to 50 at a time
curl -u "bsc_your_client_id:bss_your_client_secret" \
-X POST https://api.betterstr.com/user-api/v1/reservations/bulk \
-H "Content-Type: application/json" \
-d '{
"property_uuid": "4f0c9a2e-6b1d-4c8e-9f3a-2d7e8b1c5a60",
"reservations": [
{"reference":"BK-1002","first_name":"Marc","check_in":"2026-12-27 15:00","check_out":"2027-01-02 10:00"},
{"reference":"BK-1003","first_name":"Yuki","check_in":"2027-01-05 15:00","check_out":"2027-01-08 10:00"}
]}'Bulk calls never send notifications and report success or failure per row, so one bad date does not stop the other 49.
Step 4: your TVs
If you run BetterSTR TV in your rooms, the same key sees them.
curl -u "bsc_your_client_id:bss_your_client_secret" \
"https://api.betterstr.com/user-api/v1/android-tv?include=power"
curl -u "bsc_your_client_id:bss_your_client_secret" \
-X POST https://api.betterstr.com/user-api/v1/android-tv/2279cabafd62c2a5/message \
-H "Content-Type: application/json" \
-d '{"text":"The ski bus leaves at 8:30 tomorrow."}'Listing always works. Calls addressed to one TV (power, message, settings) need that TV to be on a plan; the free trial counts.
Try it before you code it
Open api.betterstr.com/user-api/docs, click Authorize, paste your client id and secret, and press Try it out on any call. The console runs real requests against your account, so you will see your actual properties and bookings come back. It is the fastest way to check field names and error messages before you build anything.
Prefer prose? The README walks through the whole workflow step by step, and the OpenAPI spec drops straight into Postman, Zapier, a ChatGPT Custom GPT Action or your coding assistant. If you would rather talk than type, the same key works with our Claude MCP connector, and Claude can push the bookings for you.
What it costs
Reading is free, as it always has been. Pushing bookings to a property, or changing a property’s details, needs that property on a paid plan: Guidebook Premium at $2.99 a property a month, or BetterSTR Simple at $15, which bundles the TV, WiFi marketing and upsells as well. That is the same plan that unlocks guest automations and TV check-in, so if you are pushing bookings you almost certainly want it anyway.
Creating properties through the API is available to accounts on Premium with the flat-rate option covering all properties, because each new property joins your next bill automatically and the API tells you the monthly cost in the response. On other plans you add properties in the dashboard, where you choose exactly which ones to pay for.
There are sensible limits so a runaway script cannot fill the database: 5,000 new bookings and 1,000 new properties per account per day, which is far more than any onboarding needs. If you are a hotel group with a bigger first sync, tell us and we will lift them for the day.
Frequently asked questions
Do I need to be a developer?
No. If your booking tool can call a webhook or run a Zapier, Make or n8n step, you can push bookings without writing code. The console shows you the exact request to copy.
Can I update bookings that came from my PMS?
No. Bookings synced from a connected PMS are read-only, because the PMS owns them. The write calls work on properties you added yourself.
What happens if I send the same booking twice?
It is updated, not duplicated. Your reference is the key, so re-sending your whole calendar every night is safe.
Will my guests get notified?
A brand-new booking triggers your guest automations, the same as a PMS booking. Updates, cancellations and bulk imports are silent unless you ask for notifications in the request.
Is the Partner API going away?
No. PMS vendors and large partners keep using the Partner API with their own partner key. This is for hosts and their developers, using credentials they create themselves.