PMS integration guide

This will guide you through integrating your Property Management System (PMS) / Channel Manager with Akiles. Following this guide, your integration will allow the user to:

Connect their Akiles organization.
Configure room/listing -> group mapping.
Automatically sync reservations to Akiles members.

Tip

Why map rooms to Akiles groups and not to Akiles locks/doors? A few reasons:

Guests often need access to multiple doors. For example a reservation for “Room 301” might need access to “Street door”, “Floor 3” and “Room 301”. A single group can configure access to multiple doors, so you can make your mapping “1 room = 1 group” instead of “1 room = N doors”, which is simpler to implement.
In Akiles, there’s no way to associate members to doors directly. You’d have to create a temporary groups for each reservation with the right list of doors and delete it after the reservation ends. It’d be more work!
Groups have an advanced permission system that your users can take advantage of. If you manage doors directly you’d have to reimplement all of it from scratch.

User experience

Add a section for the Akiles integration. We recommend it shows the “status” of the integration: connected or not connected. When not connected, show a button the user can click to start the connection process. When clicked, redirect the user to the OAuth authorization flow.

Once connected, we recommend displaying the following:

The organization name the integration is connected to. You can obtain it from GET /organization.
Checkboxes for enabling/disabling the different credential types.
A section where the user can configure a mapping from each room/property/listing/unit in your software to an Akiles group.

Getting started

Create an application in the Developer Center.
Create a test organization in the Developer Center. We recommend you choose the “Hotel” template, it will fill the test organization with devices and groups corresponding to a typical hotel setup.
Implement the OAuth authentication to the point you can obtain an access token + refresh token for the test org.
Use the access token to do API calls as detailed below.

API calls

The goal of the integration is to sync reservations to Akiles members. When reservations are created or edited, do API calls to Akiles to create or update the corresponding member. Here’s a list of the API calls you need to do:

On reservation created

Warning

Pay attention to time zones for the check-in and check-out times! They’re typically specified by the owner in local time, so you have to convert them to UTC. See here for more info.

POST /members
- name
- starts_at: check-in date and time, in UTC.
- ends_at: check-out date and time, in UTC.
- metadata: store the reservation ID or another metadata you might want to use to find the member later.
POST /members/{id}/group_associations
- member_group_id: the group corresponding to the room/listing that the user configured in the mapping.
- IMPORTANT: do NOT fill starts_at, ends_at here! Only fill them in the member.
Create credentials for the member, for the types the user enabled when configuring the integration:
- POST /members/{id}/magic_links
- POST /members/{id}/emails
- POST /members/{id}/pins
- POST /members/{id}/cards
If desired, send PIN/link to guest via your preferred method (email, SMS…)

On reservation dates changed

PATCH /members/{id} (update dates if needed)

On reservation room/listing/property changed

Delete the old member_group_association. DELETE /members/{id}/group_associations/{id}
Create a new member_group_association with the new group ID. POST /members/{id}/group_associations

On reservation cancel

DELETE /members/{id} (immediately revokes all access)

No need to delete credentials or group associations, just deleting the member is enough.

On reservation end

When the check-out time arrives you don’t have to do anything. There’s no need to delete the member, it automatically loses all access when the ends_at time arrives. It will be auto-deleted 1 day after ends_at passes.