Cloudbeds

Cloudbeds REST API v1.3

REST API exposing reservations, guests, rooms, rate plans, payments, webhooks, dashboard, and reporting for properties using Cloudbeds. v1.3 is the latest documented version.

GitHub OpenAPI

Documentation

📖
Documentation
https://developers.cloudbeds.com/reference

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/cloudbeds/refs/heads/main/openapi/cloudbeds-openapi.yml

Examples

📝
Example
https://raw.githubusercontent.com/api-evangelist/cloudbeds/refs/heads/main/examples/cloudbeds-reservation-example.json
📝
Example
https://raw.githubusercontent.com/api-evangelist/cloudbeds/refs/heads/main/examples/cloudbeds-guest-example.json
📝
Example
https://raw.githubusercontent.com/api-evangelist/cloudbeds/refs/heads/main/examples/cloudbeds-rate-plan-example.json

Schemas & Data

📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/cloudbeds/refs/heads/main/json-schema/cloudbeds-reservation-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/cloudbeds/refs/heads/main/json-schema/cloudbeds-guest-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/cloudbeds/refs/heads/main/json-schema/cloudbeds-rate-plan-schema.json
📊
JSONStructure
https://raw.githubusercontent.com/api-evangelist/cloudbeds/refs/heads/main/json-structure/cloudbeds-reservation-structure.json
📊
JSONStructure
https://raw.githubusercontent.com/api-evangelist/cloudbeds/refs/heads/main/json-structure/cloudbeds-guest-structure.json

Other Resources

🔗
SpectralRules
https://raw.githubusercontent.com/api-evangelist/cloudbeds/refs/heads/main/rules/cloudbeds-rules.yml
🔗
JSONLD
https://raw.githubusercontent.com/api-evangelist/cloudbeds/refs/heads/main/json-ld/cloudbeds-context.jsonld
🔗
Vocabulary
https://raw.githubusercontent.com/api-evangelist/cloudbeds/refs/heads/main/vocabulary/cloudbeds-vocabulary.yml

OpenAPI Specification

cloudbeds-openapi.yml Raw ↑ 
openapi: 3.1.0
info:
  title: Cloudbeds REST API v1.3
  description: |
    Cloudbeds REST API for property management - reservations, guests, rooms,
    rate plans, payments, housekeeping, webhooks, and reporting. v1.3 is the
    current documented version (v1.2 remains available). Authentication is via
    API keys or OAuth 2.0 for technology partners.
  version: "1.3.0"
servers:
  - url: https://hotels.cloudbeds.com/api/v1.3
    description: Cloudbeds REST API v1.3
  - url: https://hotels.cloudbeds.com/api/v1.2
    description: Cloudbeds REST API v1.2 (legacy)
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-KEY
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://hotels.cloudbeds.com/api/v1.2/oauth
          tokenUrl: https://hotels.cloudbeds.com/api/v1.2/access_token
          scopes:
            read: Read access
            write: Write access
  schemas:
    Reservation:
      type: object
      properties:
        reservationID:
          type: string
        guestName:
          type: string
        status:
          type: string
        startDate:
          type: string
          format: date
        endDate:
          type: string
          format: date
        roomTypeID:
          type: string
        total:
          type: number
    Guest:
      type: object
      properties:
        guestID:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        email:
          type: string
        phone:
          type: string
    Room:
      type: object
      properties:
        roomID:
          type: string
        roomName:
          type: string
        roomTypeID:
          type: string
    RatePlan:
      type: object
      properties:
        rateID:
          type: string
        roomTypeID:
          type: string
        rate:
          type: number
        date:
          type: string
          format: date
    Payment:
      type: object
      properties:
        paymentID:
          type: string
        reservationID:
          type: string
        amount:
          type: number
        currency:
          type: string
        type:
          type: string
    Webhook:
      type: object
      properties:
        id:
          type: string
        event:
          type: string
        endpointUrl:
          type: string
    SuccessEnvelope:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
        data:
          type: object
        count:
          type: integer
        total:
          type: integer
security:
  - apiKey: []
  - oauth2: [read, write]
paths:
  /access_token:
    post:
      summary: Obtain OAuth access token
      security: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                client_id:
                  type: string
                client_secret:
                  type: string
                grant_type:
                  type: string
                code:
                  type: string
                redirect_uri:
                  type: string
      responses:
        '200':
          description: Token returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
                  refresh_token:
                    type: string
                  token_type:
                    type: string
                  expires_in:
                    type: integer
  /userinfo:
    get:
      summary: Get OAuth user info
      responses:
        '200':
          description: User info
          content:
            application/json:
              schema:
                type: object
  /getHotels:
    get:
      summary: List hotels/properties
      responses:
        '200':
          description: Hotels collection
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
  /getHotelDetails:
    get:
      summary: Get hotel details
      parameters:
        - name: propertyID
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Hotel details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
  /getReservations:
    get:
      summary: List reservations
      parameters:
        - name: propertyID
          in: query
          required: true
          schema:
            type: string
        - name: status
          in: query
          schema:
            type: string
        - name: checkInFrom
          in: query
          schema:
            type: string
            format: date
        - name: checkInTo
          in: query
          schema:
            type: string
            format: date
        - name: pageNumber
          in: query
          schema:
            type: integer
        - name: pageSize
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Reservations list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
  /getReservation:
    get:
      summary: Get reservation
      parameters:
        - name: reservationID
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Reservation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Reservation'
  /postReservation:
    post:
      summary: Create reservation
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Reservation'
      responses:
        '200':
          description: Reservation created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
  /putReservation:
    put:
      summary: Update reservation
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Reservation'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
  /getGuestList:
    get:
      summary: List guests
      parameters:
        - name: propertyID
          in: query
          required: true
          schema:
            type: string
        - name: pageNumber
          in: query
          schema:
            type: integer
        - name: pageSize
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Guests list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
  /getGuest:
    get:
      summary: Get guest
      parameters:
        - name: guestID
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Guest
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Guest'
  /postGuest:
    post:
      summary: Create guest
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Guest'
      responses:
        '200':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
  /putGuest:
    put:
      summary: Update guest
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Guest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
  /getRooms:
    get:
      summary: List rooms
      parameters:
        - name: propertyID
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Rooms
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
  /getRoomTypes:
    get:
      summary: List room types
      parameters:
        - name: propertyID
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Room types
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
  /getAvailableRoomTypes:
    get:
      summary: Check available room types
      parameters:
        - name: propertyID
          in: query
          required: true
          schema:
            type: string
        - name: startDate
          in: query
          required: true
          schema:
            type: string
            format: date
        - name: endDate
          in: query
          required: true
          schema:
            type: string
            format: date
      responses:
        '200':
          description: Availability
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
  /postRoomAssign:
    post:
      summary: Assign room to reservation
      responses:
        '200':
          description: Assigned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
  /postRoomCheckIn:
    post:
      summary: Check guest into room
      responses:
        '200':
          description: Checked in
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
  /postRoomCheckOut:
    post:
      summary: Check guest out of room
      responses:
        '200':
          description: Checked out
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
  /getRatePlans:
    get:
      summary: List rate plans
      parameters:
        - name: propertyID
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Rate plans
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
  /getRate:
    get:
      summary: Get rate details
      parameters:
        - name: propertyID
          in: query
          required: true
          schema:
            type: string
        - name: roomTypeID
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Rate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RatePlan'
  /putRate:
    put:
      summary: Update rate
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/RatePlan'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
  /getPaymentMethods:
    get:
      summary: List payment methods
      parameters:
        - name: propertyID
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Payment methods
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
  /postPayment:
    post:
      summary: Record a payment
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Payment'
      responses:
        '200':
          description: Payment recorded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
  /postCharge:
    post:
      summary: Process a charge
      responses:
        '200':
          description: Charge processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
  /getWebhooks:
    get:
      summary: List webhooks
      parameters:
        - name: propertyID
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Webhooks list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
  /postWebhook:
    post:
      summary: Create webhook
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Webhook'
      responses:
        '200':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
  /deleteWebhook:
    delete:
      summary: Delete webhook
      parameters:
        - name: id
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
  /getDashboard:
    get:
      summary: Get dashboard data
      parameters:
        - name: propertyID
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Dashboard
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
  /getUsers:
    get:
      summary: List users on property
      parameters:
        - name: propertyID
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Users list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'