RoomKeyPMS Reservation Data API

openapi: 3.0.3
info:
  title: RoomKeyPMS POS Reservation Data API
  description: 'RoomKeyPMS''s REST API for pulling reservation and guest data, posting POS charges to a guest folio, and pulling hotel statistics/receipts. Endpoint paths, parameters, and behavior are taken directly from RoomKeyPMS''s public support documentation and version release notes. The API is partner-gated: an API key and per-hotel credentials are issued only after a hotel''s IT team emails RoomKeyPMS support and the property signs off. Responses can be requested as JSON or XML via the request header. There is no endpoint that returns only records changed since the last call; RoomKeyPMS recommends polling on a 10-15 minute cadence without parallel calls, staggered across properties for multi-property integrations. Date-ranged endpoints are capped at a 60-day window. The exact production base host is not published as a standalone value by RoomKeyPMS; it is inferred here from RoomKeyPMS''s own Help/reference portal and should be confirmed once a partner API key is issued.'
  version: 2.8.0.2
  contact:
    name: RoomKeyPMS Support
    url: https://support.roomkeypms.com/a/972656-api-documentation
servers:
- url: https://www.welcometorsi.net/RoomkeyApi/api
  description: RoomKeyPMS production API (base host inferred from the public Help/reference portal; confirm with issued credentials)
security:
- apiKeyAuth: []
tags:
- name: Reservation Data
  description: Pull reservation and guest-profile data by hotel.
paths:
  /hotels/{hotelId}/reservations/guestprofile:
    get:
      operationId: listReservations
      tags:
      - Reservation Data
      summary: List reservations by arrival date
      description: Returns reservations arriving within the given date range. Maximum range is 60 days. RoomKeyPMS recommends narrow, frequent (10-15 minute) polling windows for ongoing pulls rather than wide windows.
      parameters:
      - $ref: '#/components/parameters/HotelId'
      - $ref: '#/components/parameters/ApiKeyParam'
      - $ref: '#/components/parameters/FromDate'
      - $ref: '#/components/parameters/ToDate'
      responses:
        '200':
          description: A list of reservations.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Reservation'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /hotels/{hotelId}/reservations/guestprofile/inhouse:
    get:
      operationId: listInHouseGuests
      tags:
      - Reservation Data
      summary: List currently in-house guests
      description: Real-time snapshot of guests currently checked in at the property. Also used by POS integrations to validate a room/guest pairing before posting a charge.
      parameters:
      - $ref: '#/components/parameters/HotelId'
      - $ref: '#/components/parameters/ApiKeyParam'
      responses:
        '200':
          description: A list of in-house guests.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Reservation'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /hotels/{hotelId}/reservations/guestprofile/checkedout:
    get:
      operationId: listCheckedOutGuests
      tags:
      - Reservation Data
      summary: List checked-out guests
      description: Returns guests checked out within the given date range. Maximum range is 60 days.
      parameters:
      - $ref: '#/components/parameters/HotelId'
      - $ref: '#/components/parameters/ApiKeyParam'
      - $ref: '#/components/parameters/FromDate'
      - $ref: '#/components/parameters/ToDate'
      responses:
        '200':
          description: A list of checked-out guests.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Reservation'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /hotels/{hotelId}/reservations/guestprofile/cancellations:
    get:
      operationId: listCancellations
      tags:
      - Reservation Data
      summary: List cancelled reservations
      description: Returns reservations cancelled within the given date range.
      parameters:
      - $ref: '#/components/parameters/HotelId'
      - $ref: '#/components/parameters/ApiKeyParam'
      - $ref: '#/components/parameters/FromDate'
      - $ref: '#/components/parameters/ToDate'
      responses:
        '200':
          description: A list of cancelled reservations.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Reservation'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /hotels/{hotelId}/reservations/guestprofile/reserved:
    get:
      operationId: listReservedNotArrived
      tags:
      - Reservation Data
      summary: List reserved (not yet arrived) reservations
      description: Returns reservations that are booked but whose guests have not yet arrived, within the given date range.
      parameters:
      - $ref: '#/components/parameters/HotelId'
      - $ref: '#/components/parameters/ApiKeyParam'
      - $ref: '#/components/parameters/FromDate'
      - $ref: '#/components/parameters/ToDate'
      responses:
        '200':
          description: A list of reserved, not-yet-arrived reservations.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Reservation'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  parameters:
    ApiKeyParam:
      name: key
      in: query
      required: true
      description: API key for the requesting integration.
      schema:
        type: string
    FromDate:
      name: fromDate
      in: query
      required: true
      description: Start of the date range (local property timezone). Combined with toDate, capped at a 60-day maximum range.
      schema:
        type: string
        format: date
    ToDate:
      name: toDate
      in: query
      required: true
      description: End of the date range (local property timezone). Combined with fromDate, capped at a 60-day maximum range.
      schema:
        type: string
        format: date
    HotelId:
      name: hotelId
      in: path
      required: true
      description: The RoomKeyPMS-assigned identifier for the hotel/property.
      schema:
        type: string
  schemas:
    ChannelConfirmation:
      type: object
      properties:
        shortCode:
          type: string
          example: BKG
        name:
          type: string
          example: Booking.com
        confirmationNumber:
          type: string
    Reservation:
      type: object
      description: A reservation/guest-profile record. Field names are honestly modeled from RoomKeyPMS's documented data categories (guest profile, room and rate, booking source) since RoomKeyPMS's public articles describe the available data but do not publish a full field-level schema.
      properties:
        confirmationNumber:
          type: string
        guestName:
          type: string
        guestAddress:
          type: string
        guestEmail:
          type: string
        arrivalDate:
          type: string
          format: date
        departureDate:
          type: string
          format: date
        roomNumber:
          type: string
        roomType:
          type: string
        rateName:
          type: string
        baseRate:
          type: number
        bookingSource:
          type: string
        reservationUniqueId:
          type: array
          description: Channel-partner confirmation numbers, added in API v2.8.0.2.
          items:
            $ref: '#/components/schemas/ChannelConfirmation'
    Error:
      type: object
      properties:
        message:
          type: string
  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: query
      name: key
      description: API key issued by RoomKeyPMS after a hotel's IT team requests access and the property signs off.