Inlet API integration guide

Introduction
Prerequisites
Integration Steps
- 3.1. Obtain API Credentials
- 3.2. Implement API Endpoints
- 3.3. Validate and Verify Customer Data
Certification Process
- 4.1. Preparing for Certification
- 4.2. Submitting for Certification
- 4.3. Certification Review
- 4.4 PMS and complex integration certification
Going Live

1. Introduction

Inlet offers a robust API that enables partners to integrate their services seamlessly, providing enhanced functionalities and improved customer experiences. This guide provides detailed instructions and important considerations to ensure your integration is successful and compliant with Inlet's requirements.

2. Prerequisites

Before beginning the integration process, ensure you have:

Technical Expertise: Access to developers familiar with RESTful APIs and JSON.
Development Environment: A secure environment for development and testing.
Compliance Understanding: Knowledge of relevant data protection laws (e.g., GDPR).
Understand Use cases: Understand your business use cases, and match them with the use-cases inlet supports.

Optional — Reseller agreement:
If you wish to act as a reseller, you may sign a reseller agreement. This is not required to implement an integration. A valid reseller agreement grants you access to the reseller portal, reseller pricing tiers, and resale rights.

3. Integration Steps

3.1. Obtain API Credentials

When you are ready to test Inlet will provide you with some credentials to test, make sure to store them securely.
Important: Store these credentials securely and do not share them.

3.2. Implement API Endpoints

Step 1: Review API Documentation

Access the Inlet API Documentation.
Understand the available endpoints, request/response structures, and authentication mechanisms.

Step 2: Develop API Calls

Start with basic endpoints to establish connectivity.
Implement required endpoints for your integration, handling all HTTP methods as needed.

Step 3: Only send to Inlet when the booking starts "soon"

Do not send bookings to Inlet until it is less than 72 hours until the booking starts, we prefer 24 hours or less, but no more than 72 hours.
To reduce the need for updates in our system.

Step 4: Partner name, and Booking ID

In order for us to support you and your customers even better, we require you to populate the following fields

Partner - Name of your software or platform (String)
Booking ID - The internal ID the booking has gotten, needs to be the same as the end customer gets (String)

Step 5: Handle Errors and Exceptions

Implement comprehensive error handling based on Inlet's error and reply messages.
If there was an error the "message" part in our response clearly states what went wrong.
Responses needs to be read and acted on accordingly
Log errors securely for debugging purposes.

Step 6: Implement a retry mechanism

Some locks and requests to Inlet depend on upstream services, and temporary timeouts may occur.
If a request fails due to a timeout or temporary error, the integration must retry the request automatically.
Retries should occur every 5 minutes for a maximum of 60 minutes.
The integration must attempt the request a maximum of 30 times.
Retries must not continue indefinitely.
If the request still fails after the retry limit, the booking should be marked for manual follow-up or operational escalation.
The integration must ensure that unresolved failures are handled in time to create access before the booking start.

Step 7: Re-sync access codes upon lock replacement or configuration updates

In some cases of hardware failure, a lock may be physically replaced or its underlying system configuration updated. When this happens, previously generated access codes may no longer work on the new or updated lock. This issue will be minimized by the implementation of Step 3: Only send to Inlet when the booking starts "soon"

The integration must be able to re-sync affected bookings by sending a bulk booking update or an UpdateAccess request for those bookings. This request will generate and return a new access code, which must replace the old code in the partner system.

Instances when this workflow could be triggered:

A lock fails and is physically replaced.
A lock's settings or system configuration are updated.
Inlet or the property operator explicitly requests a re-sync for affected bookings.

The partner must ensure that guest-facing access information is automatically updated with the newly returned code.

3.3. Validate and Verify Customer Data

Critical Step: Data Verification

Inlet requires that all customer data sent through the API is accurate and verified. This ensures data integrity and compliance with legal regulations.

Step 1: Email Verification

Format Validation (required): Use regex or validation libraries to ensure email addresses conform to standard formats.
Domain Verification (optional): Check MX records to verify the domain exists.
User Verification (optional): Implement email confirmation steps where customers confirm their email addresses.

Step 2: Phone Number Verification

Format Validation (required): Use libraries to validate phone numbers, including country codes. We recommend: Google Llibphonenumber
Country Code Inclusion (required): Ensure all phone numbers include the country code in international format (e.g., +1 for USA).
User Verification (optional): Send an OTP (One-Time Password) via SMS to confirm ownership.

Step 3: Data Sanitization

Remove any malicious code or scripts from user input.
Encode data properly before transmission.

Step 4: Mandatory Fields

Ensure all required fields as per the API specification are provided.
Validate data types (e.g., strings, integers) and constraints (e.g., field lengths).

4. Certification Process

Before your integration can go live, it must be certified by Inlet to ensure it meets all technical and compliance standards.

4.1. Preparing for Certification

Step 1: Review Certification Requirements

Access the Partner Certification Process.
Understand the criteria, including technical functionality, data validation, and user experience standards.
If your integration supports PMS workflows or complex booking journeys, also review the PMS and Complex System Certification requirements.

Step 2: Documentation

Prepare technical documentation of your integration.
The documentation needs to include a basic API data flow diagram.

Step 3: Compliance Checklist

Ensure all data handling complies with legal and Inlet-specific requirements.
Verify that customer data is securely stored and transmitted.

4.2. Submitting for Certification

Complete and submit the certification request form.

4.3. Certification Review meeting

Step 1: Technical Evaluation

Inlet's team will assess the technical aspects of your integration.
You will need to demonstrate your integration with API calls, data validation, error handling, and performance.
Inlet will look at logs on their end to validate your data and compliance.
The Inlet team will verify that all customer data is properly validated and secured.

Step 2: Feedback and Corrections

If issues are found, you'll have to:
- Address all issues and resubmit any required information.
- Schedule a new certification review meeting.

Step 3: Approval

Upon successful review, you'll receive a certification approval.
Certification is valid for a specified period, after which re-certification may be required

Step 4: Re-approval

Inlet can ask you to re-certify once a year
Inlet may revoke your certification if your integration generates significant errors and you do not promptly address them.

4.4 PMS and complex integration certification

Some integrations require additional PMS or complex system certification before going live.

This applies when the integration supports more than simple one-room bookings, for example:

hotel PMS integrations
company bookings
booking company, agency, or tour operator bookings
group bookings
multi-room bookings
room changes
check-in and check-out status updates
common-door access
meeting rooms, conference rooms, or other bookable resources
booking types where guest communication should be suppressed

For these integrations, Inlet will certify the specific user journeys supported by the partner system. The goal is to verify that the correct person receives access to the correct room, door, or resource, for the correct time period — and that access is updated or revoked when the booking changes.

Only scenarios that are supported and tested are included in the certified scope. If the integration does not support a specific flow, such as group bookings, common-door access, or PMS check-in/check-out status, this must be documented.

The partner may be asked to demonstrate flows such as:

creating a standard booking
updating dates, guest details, or room assignment
cancelling or marking a booking as no-show
handling room changes
handling early check-in or late check-out
creating access for company, agency, group, or multi-room bookings
suppressing guest communication where required
creating access for common doors or other bookable resources
logging and retrying failed create, update, cancellation, or revocation events

Inlet will confirm which scenarios are certified after the certification review. Features that have not been tested are not included in the certified scope.

Re-certification may be required if the integration changes significantly, for example changes to booking logic, communication rules, room-change handling, common-door logic, group booking behavior, or error handling.

5. Going Live

After certification, you're ready to onboard your first customer.

Step 1: Obtain Production Credentials

Request API credentials for your spesified customer.
Store these credentials securely and update your configuration.

Step 2: Final Testing

Perform a final round of testing on your first customer to make sure everything works as intended.
Ensure that all user journey you support work as expected.
For PMS or complex integrations, final testing must include the certified user journeys agreed during the PMS certification process, not only the standard booking flow.

Step 3: Monitoring

Set up monitoring tools to track the performance and health of your integration.
Implement alerting mechanisms for critical issues.

Step 4: Launch

Officially launch your integration to your customer base.
Communicate the new capabilities to users and provide support resources.

By following this guide meticulously, you'll ensure a smooth integration with Inlet, providing a secure and efficient service to your customers.

We look forward to a successful partnership!

/ The Inlet tech team

Table of Contents