Exely Connect APIs (1.0.0)

To use the API, you must obtain an access token (access_token). Access tokens are issued based on the client_id and client_secret credentials.

You can obtain these credentials through a property integration.

The hotelier creates an API integration in the Exely account and provides you with the client_id and client_secret credentials. For more information, see Integration through the property.

Once you have obtained your credentials, send a request to the authorization endpoint. The response will include an access token (access_token).

Include access_token in the Authorization header of every API request:

Authorization: Bearer <access_token>

Authorization is performed using OAuth2.0.

OAuth 2.0 is a standard protocol that allows applications to obtain access to data.

To access the API, include an access token in each request. The token is issued in the JSON Web Token (JWT) format.

JWT (JSON Web Token) is a secure, compact format for transmitting information between a client and a server.

Access tokens are obtained using Client credentials flow, which requires authorization using a client secret. To request an access token, the following parameters are required:

• client_id,
• client_secret.

Exely. Authorization server: https://connect.hopenapi.com/auth/token

Rate limits

• 3 requests per second,
• 15 requests per minute,
• 300 requests per hour per IP address.

Token lifetime

Access tokens are valid for 15 minutes.

Token refresh is not supported. Once the token expires, obtain a new access token through the authorization endpoint.

Authorization endpoint

• Production: https://connect.hopenapi.com/auth/token

Decoded token example:

eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI2OGZjOHRNUGFSUHRyRHYtVHV2WEpncUNGTE1CVGRheTBpQkdJSUE3amxvIn0.eyJleHAiOjE2OTg5MTYwMzYsImlhdCI6MTY5ODkxNTEzNiwianRpIjoiYTJjZGJhMGQtYzQwNy00OWRmLThiNGQtOTJhNTM1NWQxYTFmIiwiaXNzIjoiaHR0cHM6Ly9wYXJ0bmVyLnRsaW50ZWdyYXRpb24uY29tL2F1dGgvcmVhbG1zL1BhcnRuZXJBcGkiLCJhdWQiOiJUcmF2ZWxMaW5lLlBhcnRuZXJBUEkiLCJzdWIiOiI4NmE0YjZiZS0wYTc0LTRjYjktYjNhYi1iNDYyZWUwYmIyYmQiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJwYTMiLCJzY29wZSI6IiIsImFwaV9hY2Nlc3NlcyI6WyJjb250ZW50Il19.Nz6dyaHGyIN5IKv30oM-HrqdQBqaGdzEFrk7ACUWbfvsNCHNowg96iJrGwQbkOUSVPtQJF9Cwf1_jywP6c2UPHclzBIDp9HTsYdVM5QS_k9ecs0GCiI8ACBqld3yatY4dJz3MRkxnU_rp0NbJJQ-uBcmg_9UCSCIc3mKR7UAosr5XOXeb4ckrFd67DK5xfofT0ykE46Qkc6nvev3AGx11fPAVsFnmmPOSnlpQzJTI7XBWbD120q5fDdksVlaiq3YoBueDEeOPFH08Ia6xdTVjIf_zsyOEKt2N8_7BTyWG_3YPThBbgn-eAgybSdeop6_eCrWTfQvX5g8qtR2e9J32A

You can decode the token using JWT.IO.

Decoded token example

Request body:

{
  "exp": 1698916036,
  "iat": 1698915136,
  "jti": "a2cdba0d-c407-49df-8b4d-92a5355d1a1f",
  "iss": "https://connect.hopenapi.com/auth/realms/PartnerApi",
  "aud": "Exely.ConnectApi",
  "sub": "86a4b6be-0a74-4cb9-b3ab-b462ee0bb2bd",
  "typ": "Bearer",
  "azp": "pa3",
  "scope": "",
  "api_accesses": [
    "content"
  ]
}

*Note: Refresh tokens are not used.

1. Cache the access token on the client side and reuse it in subsequent requests.

2. Use OAuth 2.0 libraries:

   • .NET:
     IdentityModel
     Microsoft.Extensions.DependencyInjection

   • JavaScript:
     oidc-client
     oidc-client-js Wiki

   • PHP:
     OpenID-Connect-PHP

   • cURL:

     curl -L -X POST "https://connect.hopenapi.com/auth/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials" \
     -d "client_id=XXXXXXXXXXXX" \
     -d "client_secret=XXXXXXXXXXXX"
     

To ensure the stability of the service, we apply limits to the number of API requests. If a limit is exceeded, the API returns a 429 Too Many Requests error and the request is not processed.

Unless otherwise specified, limits are applied separately to each API client. All requests made by the same client are counted against the same limit, regardless of the IP address or the number of access tokens used.

Request limits define the maximum number of requests that can be made per second, minute, or hour. For each incoming request, the system evaluates the number of requests made during the corresponding time window immediately preceding that request. For example, if the limit is set to 50 requests per second, the 51st request sent within the same second will be rejected. Requests can be made again once the number of requests made during the last second falls below the set limit. The same principle applies to per-minute and per-hour limits.

Each API response returns headers that help you track the remaining number of requests:

• x-ratelimit-remaining-hour - number of remaining requests within one hour from the time the request was sent
• x-ratelimit-remaining-minute - number of remaining requests within one minute from the time the request was sent
• x-ratelimit-remaining-second - number of remaining requests within one second from the time the request was sent
• retry-after is returned with the 429 Too Many Requests error and specifies the time in seconds after which the request can be retried

Swagger

Booking cancellation rules are set by the property to define the period when free cancellation is available, as well as the penalty for late cancellation. These rules are applied to selected rate plans through cancellationRuleId.

A rule can take effect starting from one of the following reference times:

• ProviderArrivalTime: Standard check-in time. For example, if the check-in time is set to 14:00, free cancellation is available until 14:00 on the day before check-in.

• ProviderDepartureTime: Standard check-out time. The cancellation period is calculated based on the property's standard check-out time applied to the check-in date. For example, if the property check-out time is set to 12:00, free cancellation is available until 12:00 on the day before check-in.

• GuestArrivalTime: Check-in time selected by the guest when booking. For example, if the standard check-in time is 14:00, but the guest selects 16:00, free cancellation is available until 16:00 on the day before check-in. If guests cannot select a check-in time, the standard check-in time is applied.

• CustomArrivalTime: Custom time from which the cancellation rule calculation starts. The time is specified in the referencePointTime field using the property's time zone.

• BookingCreationTime: The time (but not the date) when the guest made the booking. For example, if the check-in time is set to 14:00 and the guest made a booking at 09:00, free cancellation is available until 09:00 on the day before check-in.

Penalty for a specific period

A penalty is set using a time frame that includes time units and a period before the reference time.

• Time units:

  • None: Not specified, used only with the NoMatter period
  • Day: Days
  • Hour: Hours

• Period before the reference time:

  • NoMatter: Does not depend on a specific time
  • AtLeast: Greater than or equal to beforeArrivalValue.
  • NoMoreThan: Less than or equal to beforeArrivalValue.
  • Between: Within the range from beforeArrivalValue to beforeArrivalValueMax.

Penalty calculation methods

• NoPenalty: No penalty is applied
• FirstNightPercent: The penalty is a specified percentage of the first night's cost
• PrepaymentPercent: The penalty is a specified percentage of the prepayment amount
• FirstNights: The penalty equals the full cost of the first N nights

The penalty for the selected calculation method is specified as a numeric value and currency.

The rule validity period can be set by selecting check-in dates in the property's time zone. The period includes both the start and end dates. If the end date is not specified, it can be set to "Not limited", which corresponds to isEndless = true.

If the rule does not contain cancellation terms, cancellation is free of charge.

Endpoint

GET /v1/properties/{propertyId}/cancellation-rules

Retrieves booking cancellation rules

Parameters:

• propertyId (string, path): Property ID

Example:

GET /v1/properties/7291/cancellation-rules

{
  "cancellationRules": [
    {
      "id": "556875",
      "propertyId": "7291",
      "referencePointKind": "CustomArrivalTime",
      "referencePointTime": "10:57",
      "cancellationTerms": [
        {
          "beforeArrivalMatching": "Between",
          "beforeArrivalUnit": "Day",
          "beforeArrivalValue": 1,
          "beforeArrivalValueMax": 3,
          "penaltyCalculationMethod": "PrepaymentPercent",
          "penaltyValue": 10,
          "penaltyValueCurrency": "EUR",
          "arrivalDates": [
            {
              "startDate": "2024-07-11",
              "endDate": "2024-07-11",
              "isEndless": true
            }
          ]
        },
        {
          "beforeArrivalMatching": "NoMoreThan",
          "beforeArrivalUnit": "Hour",
          "beforeArrivalValue": 24,
          "penaltyCalculationMethod": "PrepaymentPercent",
          "penaltyValue": 100,
          "penaltyValueCurrency": "EUR",
          "arrivalDates": [
            {
              "startDate": "2021-02-09",
              "endDate": "2021-02-09",
              "isEndless": true
            }
          ]
        }
      ]
    }
  ]
}

Swagger

Content API retrieves photos and descriptions of the property, room types, rate plans, services, and amenities. This information is displayed in Exely Booking Engine on the property's website.

1. Main settings, description, and photos of the property
2. services - all services, including meals
3. ratePlans - rate plans
4. roomTypes - room types
5. amenities - amenities
6. Settings that are not available in the property's account:
   • currency - currency determined by the country
   • timeZone - time zone determined by the city
   • stayUnitKind - NightRate or DailyRate room sales in the booking engine determined by the property type
   • multiLocationProperty - allows different addresses for room types and can be enabled upon request to Exely customer support.

In addition, API provides available selection options.

Some common reference data, such as payment methods and property kinds, is available in the separate Reference Data API.

1. meal-plans - meal plan types, for example:
   • code EnglishBreakfast name English breakfast
   • code FullBoard name Full board
2. room-type-categories - accommodation offers. For example:
   • code Apartments name Apartment
   • code PlaceInRoom name Bed in room
   • code SmallHouse name Small house
3. room-amenity-categories - room amenities. For example:
   • group Internet and telephony code wifi_internet name Wi-Fi
   • group Furniture code journal_table name coffee table

Services

The service type can be determined by the kind field value:

• Common - any services except meals
• Meal - meals

For meals, the mealPlanCode and mealPlanName fields are provided and completed with values from the meal plans reference.

Rate plans

Rate plans are linked to other API sections:

• extraStayRuleId field - early check-in and late check-out rule (see ExtraStayRules)
• cancellationRuleId field - booking cancellation rule (see CancellationRules)

Room types

Room types are linked to references:

• categoryCode and categoryName fields - accommodation offer
• code and name elements of the amenities array - room amenities

Amenities

List of property amenities:

• code - identifier
• displayName - display name
• chargeType - charge type:
  • free - free-of-charge service
  • chargeable - paid service
  • none - charge type does not apply (the service does not require payment, for example: concierge)

Amenities with the swimming_pool and restaurant identifiers may be duplicated because there can be several of them within a single property.

Swagger

The early check-in and late check-out rules allow properties to set surcharges for early check-in and late check-out. These rules are applied to selected rate plans through extraStayRuleId.

The "Check-in and check-out" setting defines the standard check-in and check-out times that do not require an extra charge.

These rules allow properties to apply surcharges for specific time periods between the early check-in/late check-out time and the standard check-in/check-out time.

Surcharge calculation methods

• Free: free of charge
• Fixed: fixed rate
• Percent: percentage of the daily rate
• HourlyRate: hourly fixed rate
• HourlyRateAutoCalculated: hourly auto-calculated price
• Forbidden: no early check-in/late check-out

Fixed and HourlyRate allow multiple rates to be set in different currencies.

Percent allows setting a surcharge percentage and additional parameters:

• extraPlacementEnabled: 'true' if a surcharge is applied for an extra guest, 'false' if no surcharge is applied for an extra guest
• extraServiceOption: extra services with the [None, All, MealOnly] surcharge

OccupyQuota specifies whether room availability is guaranteed for an extra stay.

• true: room availability is guaranteed
• false: room availability is not guaranteed, even if the extra stay is prepaid

Endpoint

GET /v1/properties/{propertyId}/extra-stay-rules

Retrieves early check-in and late check-out rules

Parameters:

• propertyId (string, path): Property ID

Example:

GET /v1/properties/7291/extra-stay-rules

{
  "extraStayRules": [
    {
      "id": "519845",
      "propertyId": "7291",
      "checkInTime": "13:00",
      "overridesPropertyCheckInTime": false,
      "earlyCheckInPeriods": [
        {
          "startTime": "00:00",
          "endTime": "09:00",
          "chargeType": "Forbidden",
          "rates": [],
          "occupyQuota": false
        },
        {
          "startTime": "09:00",
          "endTime": "13:00",
          "chargeType": "Percent",
          "rates": [],
          "percentOptions": {
            "percentage": 0,
            "extraPlacementEnabled": false,
            "extraServiceOption": "MealOnly"
          },
          "occupyQuota": false
        }
      ],
      "checkOutTime": "12:00",
      "overridesPropertyCheckOutTime": true,
      "lateCheckOutPeriods": [
        {
          "startTime": "12:00",
          "endTime": "16:00",
          "chargeType": "Fixed",
          "rates": [
            {
              "currency": "EUR",
              "rate": 20
            }
          ],
          "occupyQuota": false
        },
        {
          "startTime": "16:00",
          "endTime": "24:00",
          "chargeType": "Forbidden",
          "rates": [],
          "occupyQuota": false
        }
      ]
    }
  ]
}

Swagger

Corporate API allows you to create a corporate customer and retrieve its data by identifier. Corporate customers are used in integrations where bookings or payments need to be associated with a legal entity.

When creating a corporate customer, the following fields are required:

1. taxpayerIdentificationNumber - Tax ID.
2. registrationReasonCode - Registration Reason Code (KPP).
3. metaData - additional information about a customer, if required by the integration.

In response, the API returns the customer's id, the legal entity name legalName and the registration details.

Swagger

Payment Methods API returns a reference of payment methods available in Partner API. This reference data can be used to map payment method codes to their corresponding types and to maintain consistency across integrations.

Each payment method includes:

1. code - payment method code.
2. type - payment method type.

Use the values from this reference when sending or processing payment information in related APIs.

Swagger

Property Amenity API returns a reference of property amenities. These values can be used to display and map amenities in user interfaces and across integrations.

Each amenity includes the following fields:

1. code - amenity code, for example, parking.
2. displayName - amenity name.
3. chargeTypeApplicable - indicates whether the amenity supports a payment type.

If chargeTypeApplicable is true, the amenity may be offered either free of charge or for an additional fee.

Swagger

Property Kind API returns a reference of property types. This reference data can be used to determine the type of a property, such as a hotel, apartment, etc.

Each property type includes the following fields:

1. id - numeric identifier of the property type.
2. displayName - property name.
3. propertyKindType - system-defined property type.

Use this reference data to store and display property types consistently across systems and integrations.

Swagger

Read Reservation API allows you to retrieve booking details from Exely Booking Engine, Exely Channel Manager, and Exely PMS.

Get booking summaries

This method returns a paginated list with brief information about each booking.

• lastModification allows you to retrieve bookings created or updated after the specified UTC date and time. If omitted, the API performs a full synchronization.

• continueToken allows you to continue retrieving the list. Its value is returned in the response of the previous request. The token does not expire. The request may return bookings that were previously retrieved but have since been updated.

• hasMoreData = false indicates that the end of the current result set has been reached. Even after this, subsequent requests may return new data created after the previous request.

If continueToken is lost, it is recommended to start a new synchronization using lastModification to obtain new continueToken.

It is recommended to set the lastModification value as follows: use the booking lastModification value minus two days. This helps avoid missing bookings in subsequent requests.

Get booking details

This method returns detailed information about a single booking.

The response includes related data available through ContentApi:

• booking.roomStays[].ratePlans[] - rate plans
• booking.roomStays[].dailyRates[].RatePlanId - rate plan identifiers
• booking.roomStays[].roomType - room types
• booking.roomStays[].services[] - services
• booking.services[] - services with the "Per booking" charge type.

Swagger

Important: A mandatory condition for using Search API is to use search results for creating bookings in Exely Suite. If this requirement is violated, API access may be disabled by the provider. To restore access, contact support@exely.com

Search API retrieves accommodations with the lowest price across all available properties (up to 200) and offers provided by a specific property.

Search data is available up to one year from the current date. Maximum number of days between arrivalDate and departureDate is 100. Maximum number of days between arrivalDate and the current date is 365.

Two additional methods are available to retrieve early check-in / late check-out information and extra services provided by a specific property. Both types of data can be retrieved in a single request: GET /api/search/v1/properties/{propertyId}/room-stays when using includeExtraStays=true and includeExtraServices=true.

Filters in aggregated search

In the method /api/search/v1/properties/room-stays/search, you can specify the following filters:

By meal availability — mealPreference.mealType. Available values:

All — returns the lowest-priced accommodation in each property.

MealOnly — returns the lowest-priced accommodation with meals included. If such an option is not available, the property is not returned.

By meal plan — mealPreference.mealsIncluded. You can specify meal plans using values returned by the following endpoints: content/v1/meal-plans — list of available meal plans,
content/v1/properties — information about all available properties, and content/v1/properties{propertyId} — information about a specific property.

Search results return the lowest-priced accommodation per property for the specified meal plans included in the rate plan. For example, if only BreakFast is specified, the response will include only the lowest-priced options with BreakFast. Options such as AllInclusive or HalfBoard are excluded.

The meal plan filter is available only when MealOnly is selected.

By minimum and maximum price — pricePreference.minPrice and pricePreference.maxPrice

These fields are optional. If provided, the search results will return the lowest-priced accommodations across all available properties based on the selected filters.

Swagger

Swagger

The methods allow you to search for and retrieve information about companies from the property's account. This information is displayed in "Property management" > "Companies".

Swagger

These methods allow you to search, retrieve, and update guest profiles and related data, including loyalty cards, bookings, and documents, for a property. The information is available in Exely PMS under the "Guest profiles" section.