Integration Account

Introduction

Integration accounts are PMS-linked accounts created on the Zepl platform to manage Host PMS connections. When onboarding a Host, you would create an Integration Account with the required configuration.This includes the following:

PMS Provider (The PMS system you are integrating with)
PMS Credentials (Could be API Key, OAuth2, Username/Password, etc.)
PMS Account Identifier (The unique identifier for the Host’s PMS account on your system)

When you create an integration account, we do the following:

Verify the credentials with the PMS
Create a new integration account on the Zepl platform
If the PMS system emits any webhook events, we subscribe to them using the subscription API.
Return the integration account ID back. You should store this in your database for future API interactions.

This integration account ID represents a Host PMS connection on the Zepl platform, and you can use it to filter out the entities in your workspace.

Schema

The integration account schema is as follows:

Field	Type	Description
id	UUID	Unique Identifier of the integration account
name	string	Name of the integration account
workspaceID	UUID	Unique Identifier of the workspace this integration account belongs to
provider	IntegrationProvider	The PMS system that this integration account is connected to. Explained below
accountIdentifier	string	Unique identifier for the account from your system.
providerAccountID	string	Unique identifier for the account from the PMS system
authType	IntegrationAccountAuthType	Authentication type. Explained below
authConfig	JSON	Authentication configuration specific to the PMS provider. Explained below
markupPercentage	number	The default markup percentage applied to the price of listings, quotes and reservations at integration account level.
defaultDiscountPercentage	number	The default discount percentage applied to the price of listings, quotes and reservations at the workspace level. Overrides the workspace level setting if any.
createdAt	Date	Integration Account creation timestamp
updatedAt	Date	Integration Account updated timestamp

Integration Provider

Currently, we support the following PMS providers:

BOOKINGSYNC
GUESTY
HOSPITABLE
HOST_TOOLS
HOSTAWAY
HOSTFULLY
HOSTFULLYSANDBOX
HOSTIFY
LODGIFY
OWNERREZ

When creating an integration account, you would have to pass a provider from the above list.

Integration Account Auth Type

Currently, we support the following authentication types:

API_KEY
ACCESS_TOKEN
OAUTH2
EMAIL_PASSWORD

When creating an integration account, you would have to pass an auth type from the above list.

Integration Account Auth Config

Each PMS provider has a different authentication configuration. We will look at the different configurations for each provider.

GUESTY

Auth Type: ACCESS_TOKEN Auth Config:

{
  "client_id": "your_client_id_here",
  "client_secret": "your_client_secret_here"
}

Sample Request:

"provider": "GUESTY",
"authType": "ACCESS_TOKEN",
"authConfig": {
    "client_id": "XXX",
    "client_secret": "XXX"
}

Auth Type: PARTNER_TOKEN Auth Config:

{
  "integration_token": "your_integration_token_here"
}

Sample Request:

"provider": "GUESTY",
"authType": "PARTNER_TOKEN",
"authConfig": {
    "integration_token": "XXX"
}

HOSTAWAY

Auth Type: ACCESS_TOKEN Auth Config:

{
  "account_id": "your_account_id_here",
  "api_key": "your_api_key_here"
}

Sample Request:

"provider": "HOSTAWAY",
"authType": "ACCESS_TOKEN",
"authConfig": {
    "account_id": "XXX",
    "api_key": "XXX"
},

HOSTFULLY

Hostfully supports both API Key and OAuth2 authentication.

API Key

Auth Type: API_KEY Auth Config:

{
  "api_key": "your_api_key_here"
}

Sample Request:

"provider": "HOSTFULLY",
"authType": "API_KEY",
"authConfig": {
    "api_key": "XXX"
},

OAuth2

Auth Type: OAUTH Auth Config:

{
  "clientRedirectURL": "your_client_redirect_url_here"
}

Sample Request:

"provider": "HOSTFULLY",
"authType": "OAUTH",
"authConfig": {
    "clientRedirectURL": "https://calry.app"
}

HOSTFULLYSANDBOX

Hostfully sandbox supports both API Key and OAuth2 authentication.

API Key

Auth Type: API_KEY Auth Config:

{
  "api_key": "your_api_key_here"
}

Sample Request:

"provider": "HOSTFULLY",
"authType": "API_KEY",
"authConfig": {
    "api_key": "XXX"
},

OAuth2

Auth Type: OAUTH Auth Config:

{
  "clientRedirectURL": "your_client_redirect_url_here"
}

Sample Request:

"provider": "HOSTFULLYSANDBOX",
"authType": "OAUTH",
"authConfig": {
    "clientRedirectURL": "https://calry.app"
}

HOSTIFY

Auth Type: API_KEY Auth Config:

{
  "api_key": "your_api_key_here"
}

Sample Request:

"provider": "HOSTIFY",
"authType": "API_KEY",
"authConfig": {
    "api_key": "XXX"
},

HOSPITABLE

Auth Type: OAUTH Auth Config:

{
  "clientRedirectURL": "your_client_redirect_url_here"
}

Sample Request:

"provider": "HOSPITABLE",
"authType": "OAUTH",
"authConfig": {
    "clientRedirectURL": "https://calry.app"
}

OwnerRez

Auth Type: EMAIL_PASSWORD Auth Config:

{
  "advertiserId": "XXX",
  "username": "XXX",
  "password": "XXX"
}

Sample Request:

"provider": "OWNERREZ",
"authType": "EMAIL_PASSWORD",
"authConfig": {
    "advertiserId": "XXX",
    "username": "XXX",
    "password": "XXX"
},

Note: The advertiserId is sometimes also referred to as the Merchant of Record (MoR) ID. This is the ID unique to your hosts. The username and password on the other hand, is common to all integration accounts in your workspace. You can obtain this by reaching out to OwnerRez. For each new connection, you should input only the advertiserId from the host, but use the same username and password when sending a request to the Zepl server.

Lodgify

Auth Type: API_KEY Auth Config:

{
  "api_key": "XXX"
}

Sample Request:

"provider": "LODGIFY",
"authType": "API_KEY",
"authConfig": {
    "api_key": "XXX"
},

Uplisting

Auth Type: API_KEY Auth Config:

{
  "api_key": "XXXXXXX",
  "client_id": "YYYYYYY"
}

Sample Request:

"provider": "UPLISTING",
"authType": "API_KEY",
"authConfig": {
    "api_key": "XXX",
    "client_id": "YYY"
},

The client ID can be obtained by reaching out to Uplisting. It is passed in the header X-Uplisting-Client-ID when making requests to Uplisting endpoints.

BEDS24

Auth Type: ACCESS_TOKEN Auth Config:

{
  "invite_code": "your_invite_code_here"
}

Sample Request:

"provider": "BEDS24",
"authType": "ACCESS_TOKEN",
"authConfig": {
    "invite_code": "XXX"
},

HOST_TOOLS

Auth Type: ACCESS_TOKEN Auth Config:

{
  "auth_token": "your_auth_token_here"
}

Sample Request:

"provider": "HOST_TOOLS",
"authType": "API_KEY",
"authConfig": {
    "auth_token": "XXX"
},

CIIRUS

Auth Type: API_KEY Auth Config:

{
  "account_id": "your_account_id_here"
}

Sample Request:

{
  "provider": "CIIRUS",
  "authType": "API_KEY",
  "authConfig": {
    "account_id": "XXX"
  }
}

Reauthorizing an Integration Account

For OAuth-based integration accounts, you may need to reauthorize the connection if the token expires or becomes invalid. Use the reauthorize endpoint to initiate a new OAuth flow:

POST /api/v1/integration-account/{integrationAccountId}/reauthorize

{
  "clientRedirectURL": "https://your-app.com/callback",
  "notificationURL": "https://your-app.com/webhook/oauth-result",
  "name": "Updated Account Name"
}

Field	Type	Required	Description
clientRedirectURL	string	Yes	URL to redirect the user after OAuth completes
notificationURL	string	Yes	Webhook URL to receive the OAuth result
name	string	No	Optionally update the account name

The response includes an oAuthURL that the user should be redirected to in order to complete the authorization.

When reauthorization starts, the integration account is set to INACTIVE and existing webhooks are cleared. The account is reactivated once the OAuth flow completes successfully.

This endpoint only works for accounts with OAuth-based authentication. Attempting to reauthorize a non-OAuth account will return an error.

Moving an Integration Account to a Different Tenant

The default tenant can move an integration account (and all associated data) to a different tenant within the same workspace:

PATCH /api/v1/integration-account/{integrationAccountId}/move-tenant

{
  "tenantID": "target-tenant-uuid"
}

This is a transactional operation that moves:

The integration account itself
All reservations under the account
All promotions linked to the account’s listings
Updates imported listing references across tenants

Only the default tenant can perform this operation. The target tenant must exist within the same workspace.

Applying Tags to All Listings

You can apply one or more tags to all listings under an integration account:

POST /api/v1/integration-account/{integrationAccountId}/apply-tags

{
  "tagIDs": ["tag-uuid-1", "tag-uuid-2"],
  "requireListingApproval": false
}

This applies each specified tag to every listing belonging to the integration account. See the Tags guide for more information on managing tags.

Get Started

Core Concepts

Amenity Mapping

Integration Account

Introduction

Schema

Integration Provider

Integration Account Auth Type

Integration Account Auth Config

GUESTY

HOSTAWAY

HOSTFULLY

API Key

OAuth2

HOSTFULLYSANDBOX

API Key

OAuth2

HOSTIFY

HOSPITABLE

OwnerRez

Lodgify

Uplisting

BEDS24

HOST_TOOLS

CIIRUS

Reauthorizing an Integration Account

Moving an Integration Account to a Different Tenant

Applying Tags to All Listings

Get Started

Core Concepts

Amenity Mapping

​Introduction

​Schema

​Integration Provider

​Integration Account Auth Type

​Integration Account Auth Config

​GUESTY

​HOSTAWAY

​HOSTFULLY

API Key

OAuth2

​HOSTFULLYSANDBOX

API Key

OAuth2

​HOSTIFY

​HOSPITABLE

​OwnerRez

​Lodgify

​Uplisting

​BEDS24

​HOST_TOOLS

​CIIRUS

​Reauthorizing an Integration Account

​Moving an Integration Account to a Different Tenant

​Applying Tags to All Listings

Introduction

Schema

Integration Provider

Integration Account Auth Type

Integration Account Auth Config

GUESTY

HOSTAWAY

HOSTFULLY

HOSTFULLYSANDBOX

HOSTIFY

HOSPITABLE

OwnerRez

Lodgify

Uplisting

BEDS24

HOST_TOOLS

CIIRUS

Reauthorizing an Integration Account

Moving an Integration Account to a Different Tenant

Applying Tags to All Listings