Cloudbeds API technical guide
For administrators and technical users connecting third-party modules to Cloudbeds.
Overview
The Cloudbeds API is a REST interface that allows authorised third-party applications to read and write data in a Cloudbeds property account. Every request must be authenticated with an API key generated from the Cloudbeds admin panel. Requests are made over HTTPS and responses are returned as JSON.
Authentication
Include your Cloudbeds API key in the X-Api-Key header of every request. Example: X-Api-Key: <your-cloudbeds-api-key>. Keys must be kept confidential. If compromised, revoke it from the Cloudbeds admin panel and generate a new one immediately.
Main endpoint categories
- Reservations: GET/POST/PATCH operations on reservation records. Includes arrival/departure, room type, rate plan, guest contact details, source channel, payment status.
- Rates: GET to retrieve current rates; POST to push updates over specific date ranges and room types. Required for the Multi-Property Consolidated Dashboard and Multi-Property Consolidated Dashboard modules.
- Guest profiles: GET the profile by reservation or by guest ID; POST to update profiles. Required for the Digital Guest Registration Card and Guest CRM modules.
- Channels: GET to list connected channels and their status. Read only; channel connections are managed inside the Cloudbeds channel manager interface.
- Reports: GET night audit data, the pickup report, occupancy summary. Required for the Automated Invoicing and Yield Management modules.
- Webhooks: register a webhook URL to receive event notifications (new booking, check-out, cancellation). Required for the Guest CRM module.
Rate limiting
Cloudbeds enforces a per-API-key rate limit. Exceeding it returns HTTP 429. Implement exponential back-off: wait 1s on the first 429, 2s on the second, 4s on the third, and so on. Batch requests by date range wherever possible rather than calling per night, to minimise call volume.
Error handling
| HTTP status | Meaning | Action |
|---|---|---|
| 200/201 | Success | Process the response normally |
| 400 | Invalid request — malformed payload | Check the request structure against the API documentation |
| 401 | Unauthorised — invalid API key | Verify the API key is correct and not revoked |
| 403 | Forbidden — insufficient permissions | Verify the API key scopes inside Cloudbeds |
| 404 | Resource not found | Verify the reservation or rate-plan identifier |
| 429 | Rate limit exceeded | Apply exponential back-off |
| 500/503 | Cloudbeds server error | Retry after 60s; contact Cloudbeds support if it persists |
Test environment and sandbox
Cloudbeds provides a sandbox environment for API testing on certain subscription tiers. Ask your Cloudbeds account manager for access. Cloudpmsbed runs integration tests against the Cloudbeds sandbox before every module release and after every Cloudbeds API update notification.