Room Access Key API is used to read or write room door pin numbers, key storage pin, or other type of room access types. Room Access Key is a generic name for anything that gives guest access to the room - pin, physical key or other types of access in the future. This API allows to:

• Reading the PIN to, for example, send the guest an sms with their room’s number and PIN. We expect most integrations to care only about reading PINs.
• For door lock or key storage integrators, inform 3RPMS of what PIN is being used for a reservation, for other integrations to use.

Reading Room Access Key¶

For most integrations only reading PIN will be relevant.

Currently two types of PINs can be present on a room:

• RoomAccessPin is used for pins with direct access to the room and used for the entire duration of the stay, e.g., door locks
• RoomAccessKeyStorage is used for key storage that, after entering pin, will give the guest a physical key to use. This pin is meant to be used only once on arrival, and may not function after.

Example query¶

Given a reservation room’s id, to retrieve a pin for a specific room:

# Variables:
# {
#   "roomId": "<room id>"
# }
query RoomAccessKey($roomId:ID!) {
  room_stays(filter:{id:{eq:$roomId}} first:1) {
    edges {
      node {
        room_setup { name }
        roomAccessKey {
          ... on RoomAccessPin { pin }
          ... on RoomAccessKeyStorage { pin }
        }
      }
    }
  }
}

A reservation may contain multiple rooms, and each room may have a different room access key. To retrieve pins for all rooms inside a reservation, when you have the reservation’s code (not to be confused with reservation’s id):

# Variables:
# {
#   "reservationCode": "<reservation code>",
#   "roomCursor": null
# }
query ReservationRoomAccessKeys($reservationCode:String! $roomsCursor:String = null) {
  reservations(filter:{code:{eq:$reservationCode}}) {
    edges {
      node {
        rooms(first:20 after:$roomsCursor) {
          edges {
            node {
              room_setup { name }
              roomAccessKey {
                ... on RoomAccessPin { pin }
                ... on RoomAccessKeyStorage { pin }
              }
            }
          }
          pageInfo { hasNextPage endCursor }
        }
      }
    }
  }
}

In the response, roomAccessKey.pin can be an alpha-numerical string with length up to 10 characters. RoomAccessKeyStorage will also contain a compartment field, but that must not be shown to end guests.

Room Access Key Changes¶

Room access key can change at any time before arrival, or during stay. See webhooks guide, if your integration requires the latest room access keys.

Writing Room Access Key¶

Basic Flow¶

1. createRoomAccessKey() creates a room access key. Until added to a room stay, this will not be visible to users or other integrations.
2. addRoomAccessKey() assigns a room access key to a room stay. Recommended to do this at least a day before arrival, so that arrival instructions can be sent to guest beforehand.
   • Integrations can add only keys it has created with createRoomAccessKey()
   • Same key can be assigned to multiple rooms at the same time
   • Each room stay can have only one key assigned to it.
3. removeRoomAccessKey() removes room access key from a room stay.
   • Integrations can remove only its own keys
4. deleteRoomAccessKey() deletes a room access key; it has to be removed from any room stays first. 3RPMS will delete keys 2 days after departure (or 2 days after not being assigned to any room).
   • Integrations can delete only keys its own keys

1. Create a Room Access Key¶

There are two types of room access keys - RoomAccessPin and RoomAccessKeyStorage. Either can be created with the same mutation by providing different variables for each:

mutation CreateRoomAccessKey($input:CreateRoomAccessKeyInput!) {
    createRoomAccessKey(input:$input) {
        roomAccessKey { id }
    }
}

In response, you’ll get an id that you need to save, to assign to a room stay and keep track of.

{
  "input": {
    "roomAccessPin": {
      "pin": "1234567890"
    }
  }
}

{
  "input": {
    "roomAccessKeyStorage": {
      "pin": "1234567890",
      "compartment": "3R"
    }
  }
}

2. Assign a Room Access Key¶

A newly created room access key will not be used for anything. For hotel staff and other systems to be aware of a Room Access Key, it has to be assigned to a Room Stay. Assignment is done the sameway for all Room Access Key types:

# Variables:
# {
#   "addRoomAccessKey": {
#     "roomStayId": "<room stay id>",
#     "roomAccessKeyId": "<room access key id>"
#   }
# }
mutation AddRoomAccessKey($addRoomAccessKey: AddRoomAccessKeyInput!) {
  addRoomAccessKey(input:$addRoomAccessKey) {
    roomStay {
      room_setup { id name }
      arrival: reservation_from
      departure: reservation_to
      roomAccessKey { id }
    }
  }
}

3. Listen for Room Stay Changes¶

Room Stay arrival, departure and physical room can change at any time. Your integration may need to listen for room changes so that a pin works when, for example, booking is moved up by a week.

Scenarios to handle:

• Arrival/Departure change
• Room Stay moved to a different physical room
• Room Stay deleted
• Reservation cancelled or re-activated
• Room Stay created
  • In some cases, a newly created room stay may use an already existing room access key. For example, when an existing room stay is split in two separate ones.

Most scenarios are applicable only when using door pin, but some are relevant for key storage as well.

There’s two approaches for this:

1. Polling - Loading data every minute to see if any relevant rooms or reservations have changed.
2. Webhooks - Receive a webhook from 3RPMS whenever some data changes.

Polling¶

Polling is not recommended, as (1) updates will always be delayed, and (2) easy to go over rate limits. That said, for simple and small scale deployments this approach may be suitable.

To cover the previous scenarios in an optimal way, two queries are needed:

1. Read rooms for all current keys you control
2. Read rooms in a given date period

Changes to rooms with assigned Room Access Key¶

# Variables
# {
#   "roomAccessKeyIds": ["abc", "def"],
#   "idsCount": 2
# }
query RelevantRoomStays($roomAccessKeyIds: [ID!]! $idsCount:Int! $roomsCursor:String = null) {
  roomAccessKeys(filter:{id:{in:$roomAccessKeyIds}} first:$idsCount) {
    edges {
      node {
        id
        roomStays(first:20 after:$roomsCursor) {
          edges {
            node {
              arrival: reservation_from
              departure: reservation_to
              room_setup { id }
              reservation { status }
            }
          }
        }
      }
    }
  }
}

In the previous query variables, roomAccessKeyIds is ids of Room Access Keys your integration controls.

Changes to rooms in a given date period¶

Retrieves all non-cancelled rooms that arrive or stay between Jan 30^th and Feb 5^th

# Variables
# {
#   "start": "2023-01-30",
#   "end": "2023-02-05"
# }
query RoomStays($start:Date! end:Date! $cursor:String=null) {
  room_stays(filter:{reservation_from:{le:$end} reservation_to:{gt:$start}} first:20) {
    edges {
      node {
          room_setup { id }
          arrival: reservation_from
          departure: reservation_to
          roomAccessKey { id }
      }
    }
  }
}

Webhooks¶

The recommended approach is using webhooks. Relevant webhooks events to listen for changes:

• room_stay.created - In some cases\, a newly created room stay may use a previously created key. E.g.\, when an existing room stay is split in two separate ones.
• room_stay.updated - Changes to arrival\, departure or physical room may be of interest.
• room_stay.deleted - When a room stay\, that had your integration’s key assigned\, is deleted\, your integration may need to remove some access on your side.
• reservation.updated - When a reservation\, that had your integration’s key assigned\, is cancelled\, your integration may need to remove some access on your side. Similarly when a reservation is activated.
• room_access_key.deleted

See webhooks guide on how to use them.

4. Revoke a Room Access Key¶

A Room Stay can have only on Room Access Key assigned. To change pin, or assign a different Room Access Key, the previous one has to be revoked. This is the same for all Room Access Key types:

# Variables
# {
#   "removeRoomAccessKey": {
#     "roomStayId": "<room stay id>",
#     "roomAccessKeyId": "<room access key id >"
#   }
# }
mutation RemoveRoomAccessKey($removeRoomAccessKey:RemoveRoomAccessKeyInput!) {
  removeRoomAccessKey(input:$removeRoomAccessKey) {
    roomStay {
      id
      roomAccessKey {
        id
      }
    }
  }
}

5. Delete a Room Access Key¶

After departure, or when your integration knows the key is no longer needed, its recommended to delete the room access key. Only Room Access Keys that have not been assigned to any rooms can be deleted.

# Variables
# { 
#   "roomAccessKeyId": "abc"
# }
mutation DeleteRoomAccessKey($roomAccessKeyId:ID!) {
  deleteRoomAccessKey(input:{roomAccessKeyId: $roomAccessKeyId}) {
    deleted
  }
}