3. IAPI Endpoints & Swagger

1. Once you receive the credentials, we would recommend you to try out the API using our Swagger available at below URL to get familiar with the API:

https://app.swaggerhub.com/apis/PriceLabs/price-labs_connector/1.0.0

2. The base URL for all API calls is available on the above mentioned swagger.

4. Security
   

1. PMS requests to PriceLabs:

There are two required security headers X-INTEGRATION-TOKEN is initially provided by PriceLabs and can be regenerated using endpoint by the PMS, and X-INTEGRATION-NAME which is provided by PriceLabs and is constant.

2. PriceLabs requests to PMS:

The following components will be combined into two signatures: a set of headers, a version string, and the json string body. They will be signed using your integration token.

Example values:

version = “v1”

headers["X-SOURCE"] = “request_source”

headers["X-PL-TIMESTAMP"] = “request_timestamp”

headers["X-PL-REQUESTID"] = “request_id”

body = "{\"test\":\"body\"}"

These example values would be combined as follows in pseudo code:

api_token = "26eea40c-f297-4b68-aeb8-bb626fe4b5e5"

header_components = "v1:request_source:request_timestamp:request_id"

signed_headers = "v1." + sha256_sign( header_components, api_token )

body_components = signed_headers + "{\"test\":\"body\"}"

signed_body = sha256_sign( body_components, api_token )

And these will be provided as the following headers:

headers["X-PL-SIGNED-HEADERS"] = signed_headers

headers["X-PL-SIGNED-BODY"] = signed_body

After calculating the signature of what you receive you can compare to the signing headers provided in the request.

To verify your implementation the signatures of the examples are provided :

headers["X-PL-SIGNED-HEADERS"]="v1.567425e5a91b576652d591cabea78e9e1fe017d1c67e2d812ae2859c355965ff"

headers["X-PL-SIGNED-BODY"]="5011b348ff6691bb9cbe93f85ffb836ef0e3fec45a4ce924f5940cb1aa4071b8"

The version can be identified in the header by splitting on the first ‘.’, where the string before it is the version, like v1 in the above signed header.

5. PMS URL Configuration

The PMS will need to set up the following 3 URLs in order to receive the pricing information. Kindly make a note of the mandatory ones:

1. Sync URL(mandatory)

1. This endpoint needs to be created and controlled by the PMS.

2. The PMS should provide this endpoint to PriceLabs using /integration endpoint 

3. PriceLabs will call this endpoint and push the listings along with the associated prices and settings as mentioned in the Pricing Features in this document.

4. If the sync URL trigger fails, we retry it 10 times on that calendar day.

2. Calendar Trigger URL(mandatory)

1. This endpoint needs to be created and controlled by the PMS.

2. The PMS should provide this endpoint to PriceLabs using /integration endpoint

3. This endpoint will receive listing_ids which are in need of a full refresh of their information.

4. Once this endpoint is triggered by PriceLabs, the PMS should send a full calendar including the latest prices and availability using the /calendar endpoint.

3. Hook URL

1. This endpoint is optional for the PMS, but needs to be created and controlled by the PMS, if they want to implement it.

2. The PMS should provide this endpoint to PriceLabs using /integration endpoint

3. If this URL is configured, PriceLabs may call this endpoint in order to send notifications to the PMS with specific information relevant for a listing. 

4. This endpoint may also be used to notify the PMS in case of errors or missing data for a listing.

6. Pricing Features

As a part of our dynamic pricing solution, we can support the following pricing features through our API. It is advised to at least support the ones marked as mandatory* since these are the bare minimum requirements for our integration. Having support for the other features creates a more robust integration that allows customers to take full advantage of PriceLabs’ features.

1. Prices*

2. Min-Stay*

3. Check in and Check Out restrictions

4. Length of Stay(LOS) pricing

5. Multi-unit - A property/listing having multiple units within.

6. Weekly and Monthly discounts

7. Extra person fee and extra person trigger(after how many guests extra person fees should be applied)

7. API Calls

The communication between PriceLabs and PMS is a two-way communication, in which some APIs are hosted by PriceLabs and others need to be implemented and hosted by the PMS. Please find the API calls provided by PriceLabs. Some of these API calls are mandatory while others are optional.

1. Integration 

1. Endpoint: /integration

2. Mandatory: Yes

3. Prerequisite: PMS should receive API credentials from PriceLabs. This is a standalone API call.

4. Description:

• This endpoint will be used to update and maintain the PMS integration. Primarily, this endpoint is used to update the following critical information:

• To update sync_url, calendar_trigger_url and hook_url

• To refresh API token
  

• To control which pricing ‘features’ are exposed to the users, such as minimum stay,| check in/out restrictions, weekly/monthly discounts, extra person fees, etc. 
  

2. Listings

1. Endpoint: /listings

2. Mandatory: Yes

3. Prerequisite: 

1. Client creates/updates listings and their attributes in PMS.

2. The client must be registered with PriceLabs and must enable PMS to push listing attributes and prices to PriceLabs.

4. Description:

• In order to receive pricing recommendations, this API call must be made for a newly created listing or to push updates to an existing listing. It is critical that this call is made for any new listings to be added in PriceLabs, otherwise PriceLabs will not be able to provide pricing recommendations for the newly created listing inside your PMS.

• While making this call, it is mandatory to provide the client’s registered email ID in the user_token parameter of the request. This is the same email ID with which the client is registered with PriceLabs.

• 
  

• 

• 
  

• Important: The listing_id that gets pushed to PriceLabs should be unique on the PMS. By uniqueness we mean that a listing_id XYZ cannot belong to two or more users in your PMS and is exclusive to one particular user. For example, the listing_id “L2001” is being used for two different properties belonging to| different users. Such cases would create ambiguity.

3. Calendar

1. Endpoint: /calendar

2. Mandatory: Yes

3. Prerequisite: /listings

4. Description:

• This endpoint will be used to update the calendar of a listing with daily price and availability. Without this call, PriceLabs will not be able to derive dynamic pricing for the specified listing.

• The calendar request for a newly added listing must contain a minimum of 730 days of rates and availability. Once a full calendar has been pushed to PriceLabs, the successive calls may be used to push updates to the entire calendar or a specific range of dates. 

• We recommend using this API to push any updates that occur in a listing’s rate and availability for a specified calendar duration to keep PriceLabs up to date, so that the PMS can eventually push only updates in the calendar (only delta, not the full calendar)

• At a minimum, price and availability must be updated for each date. The other settings need not be, however in order to receive a diff instead of the full settings with each sync you must keep them all up to date.

4. Get Prices

1. Endpoint: /get_prices

2. Mandatory: No, but recommended to implement

3. Prerequisite: This API can be called once sync URL is triggered by PriceLabs 

4. Description:

• After the listings are configured along with prices and availability using /listings and /calendar endpoints, PriceLabs will trigger the sync URL provided by the PMS as soon as new prices are ready.

• Once the PMS receives the sync URL trigger, they can either consume the prices in the sync URL trigger’s body, or call /get_prices in order to fetch the latest dynamic prices for their listings. 

• Usually this call should be made once a day, when the sync URL is triggered. In some cases, it could be more than once a day, if the customer wants to publish the latest dynamic prices to go live sooner.

• It is important to note that the PMS should not set up a CRON job for calling this endpoint, but rather only call it after the sync URL is triggered.

• This call is optional, since prices are also pushed within the message posted on sync URL. PMS may consume the prices from the sync URL if they do not wish to call get_prices.

• As a standard procedure, in case of a failed sync URL trigger, we retry the sync URL 10 times on a calendar day.

5. Reservations

1. Endpoint: /reservations

2. Mandatory: Yes. This API enables the Portfolio Analytics tools for customers.

3. Prerequisite: The listing for which reservations are posted, should be successfully configured in PriceLabs

4. Description:

• This endpoint is used to add a new reservation or update an existing reservation for a listing. 

• It is recommended to call this endpoint whenever there are new reservations or updates or cancellations to an existing reservations as this information is used within the Portfolio Analytics product which the customers use to see various trends and compare their listings’ performance with the market.

• An important note to mention is that the total_cost field in reservations request should include the sum of all associated costs including fees and taxes. 

• For accurate occupancy calculations, it is important to also provide calendar blocks (owner blocks, maintenance blocks, etc.) as reservations with a cost of $0 and a status of BLOCKED.

6. Status

1. Endpoint: /status

2. Mandatory: No

3. Prerequisite: Listings should be configured in PriceLabs

4. Description:

• This endpoint is used to pull information from PriceLabs on the current state of associated data. 

• Information can be pulled for reservations, listings, and listing calendars. 

• This would not have a direct impact on the user’s data or experience, but can be used by your PMS to validate information, debug during integration creation, or provide support to users of the established integration.
  

8. Example Integration Flow

For demonstration purposes, we will use an adhoc name ‘Fancy Rentals’ as a PMS that wants to integrate with PriceLabs. Once Fancy Rentals receives the Integration token and name from PriceLabs, they can then make API calls as explained in the previous section.

1. First, Fancy Rentals should call /integration endpoint to update the PMS URLs(section 5) and to fetch the Integration Token. If the PMS URLs are not set, the rest of the API calls that follow, may not work as expected. Fancy Rentals must store the Integration token at their end to make API calls to PriceLabs. If they need a new token, they can call this endpoint again to get a new token. 

2. Whenever a user creates a new listing in Fancy Rentals and adds their rates and availability, Fancy Rentals should call /listings endpoint for new listings followed by /calendar call to send a minimum of 12 months and upto 2 years of rates and availability. 

3. Whenever a user updates the rates and availability of their listings in Fancy Rentals, they should call /calendar to update the same in PriceLabs

4. Whenever PriceLabs calls the calendar trigger URL with the listing Ids, Fancy Rentals should call /calendar with a full refresh of rates and availability for the listings sent by PriceLabs.

5. When the user sets price customizations and turns the listing sync ‘ON’ or initiates a manual sync in PriceLabs, PriceLabs will call the sync URL given by Fancy Rentals with the listing IDs along with their dynamic prices and other settings. Fancy Rentals may call /get_prices to fetch the same, if needed.

6. When Fancy Rentals receive reservations from the user or other channels, they should call /reservations endpoint to send the reservation details to PriceLabs. Since new reservations/cancellations also change availability, it is recommended that PMS should also subsequently call the /calendar call to update the latest availability and rates.

9. Certification

Once the PMS has complemented the development, we request them to inform PriceLabs about the same so that certification can be done. We will assist the PMS team in every step of this certification process. Please note that your PMS will be generally visible to all customers in the PMS dropdown only after certification is completed. 

1. Please find below the link to our certification checklist, that the PMS should verify their integration with.

https://docs.google.com/spreadsheets/d/18mMq8Qwv_LIalrxgiud_qHeRk4SPjeHtcC8wEYHcxOo/edit#gid=0

2. We also request the PMS team to share some information regarding the integration along with the marketing information. The details can be found in the same certification checklist.

3. The checklist also consists of the verification tests that we need to run in order to make sure that the API flow is implemented correctly. 

1. These can be run by PriceLabs using a test account on the PMS and a test user in PriceLabs OR 

2. If a test account on PMS cannot be created or shared, then the PMS team and PriceLabs team can run these tests over a pre-scheduled call.

10. Go-Live

Once the certification is complete, the PMS is ready to go live with PriceLabs.

1. PMS should configure their production URLs in PriceLabs - sync URL, calendar trigger URL and hook URL and fetch the latest integration token.

2. PMS and Pricelabs, together, should identify the prospective clients to go live with. Ideally, a set of such clients should be selected so that the integration can be checked to be fully functional in the correct way. PriceLabs will enable the integration for the selected clients.

3. Once the integration is identified to be working seamlessly and without any issues for the selected clients, then it can be enabled for all clients in PriceLabs in agreement with the PMS.