Who can integrate

Steps to integrate

Pre-Integration

1. Generating credentials
   
1. The following credentials are required to access PriceLabs IAPI:
   
1. X-INTEGRATION-NAME X-INTEGRATION-TOKEN
   
2. Kindly reach out to support@pricelabs.co to request these credentials.
   
2. Our integration team will be in touch to share the relevant credentials for accessing PriceLabs IAPI.
   
2. Trying out and getting familiar with our end points using Swagger
   
1. Once you receive the credentials, we recommend exploring our API using Swagger, an interactive tool for testing endpoints.
   
2. The base URL for all API calls is provided in the swagger documentation.
   

Development and certification

Development phase

1. 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 the /integration endpoint by the PMS.  X- INTEGRATION-NAME is provided by PriceLabs and is constant.
   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 it 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 (e.g., v1 in the above signed header).
   
   Note: The sha256_sign function refers to an HMAC-SHA256 signing operation using the api_token as the key.
   
   
2. PMS URL Configuration: The PMS must 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 must be created and hosted by the PMS.
   
2. The PMS should provide this endpoint to PriceLabs via the /integration endpoint.
   
3. PriceLabs will call this endpoint to push  prices and settings (e.g., min-stay restrictions) for the specified existing listings as detailed in the Pricing Features section of this document.
   
4. If the sync fails, PriceLabs retries upto 10 times on the same calendar day.
   
   
2. Calendar Trigger URL (mandatory)
   
1. This endpoint must be created and hosted by the PMS.
   
2. The PMS should provide this endpoint to PriceLabs using the /integration endpoint.
   
3. PriceLabs will send listing_ids needing a full data refresh.
   
4. Upon trigger, the PMS should respond by sending a full calendar (latest prices and availability) via the /calendar endpoint.
   
   
3. Hook URL (mandatory)
   
1. This endpoint must be created and hosted by the PMS.
   
2. The PMS should provide this endpoint to PriceLabs using the /integration endpoint.
   
3. PriceLabs always sends notifications, such as errors or missing data for a listing in case of sync failures and in case of API timeouts. 
   
   
3. 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. Supporting the other features creates a more robust integration that allows customers to take full advantage of PriceLabs’ features.
1. Prices*: Base nightly rates for listings.
   
2. Min-Stay*: Minimum stay requirements per date.
   
3. Check in and Check Out restrictions: Restrictions on allowed check-in/out days.
   
4. Length of Stay(LOS) pricing: Discounts or surcharges based on length of stay.
   
5. Multi-unit: A property/listing having multiple units within.
   
6. Weekly and Monthly discounts: Discounts for weekly and monthly stays..
   
7. Extra person fee and extra person trigger: Fees applied per person per night, beyond a certain number of guests identified by the extra person trigger.
   
   
4. API Calls
   
   The communication between PriceLabs and PMS is a two-way communication, with some APIs hosted by PriceLabs and others implemented and hosted by the PMS. Below are the API calls provided by PriceLabs. Some 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
   
1. This endpoint will be used to update and maintain the PMS integration. Primarily, this endpoint is used to update the following critical information:
   
2. To update sync_url, calendar_trigger_url and hook_url
   
3. To refresh API token
   
4. 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:
   
1. To receive pricing recommendations, call this endpoint for new listings or updates. It's critical for adding new listings to PriceLabs; otherwise, no recommendations will be available for them in your PMS.
   
2. It is mandatory to provide the client’s email ID (registered with PriceLabs) in the “user_token” parameter of this request. 
5. Important: Each listing_id pushed to PriceLabs must be unique across the PMS, assigned exclusively to one user and not reused for multiple users' properties to prevent ambiguity. In case the listing_id isn’t unique, it is suggested to make it unique by appending the client's unique identifier to the listing id.
   
3. Calendar
   
1. Endpoint: /calendar
   
2. Mandatory: Yes
   
3. Prerequisite: /listings
   
4. Description:
   
1. This endpoint is 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.
   
2. 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.
   
3. We recommend using this API to push any updates (only delta changes and not the full calendar) that occur in a listing’s rate and availability for a specified calendar duration to keep PriceLabs up to date.
   
4. At a minimum, price and availability must be updated for each date. 
   
4. Get Prices
   
1. Endpoint: /get_prices
   
2. Mandatory: No, but recommended to implement
   
3. Prerequisite: This API should only be called once the sync_url  is triggered by PriceLabs
   
4. Description:
   
1. After the listings are configured along with prices and availability using /listings and /calendar endpoints, PriceLabs will trigger the sync_url  configured by the PMS as soon as new prices are ready.
   
2. 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.
   
3. 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.
   
4. 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.
   
5. This call is optional, since prices are also pushed within the message posted onsync_url . The PMS may consume the prices from the sync_url  if they do not wish to call /get_prices.
   
6. As a standard procedure, in case of a failed sync_url  trigger, PriceLabs retries the sync 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:
   
1. This endpoint is used to add a new reservation or update an existing reservation for a listing.
   
2. It is recommended to call this endpoint whenever there are new reservations or updates or cancellations to  existing reservations. This information is used within the Portfolio Analytics product used by customers to view trends and compare their listings’ performance with the market.
   
3. The total_cost field in reservations request should include the sum of all associated costs including fees and taxes.
   
4. The rental_revenue field in the reservations request should be the nightly prices excluding any fees, taxes or discounts.
   
5. For accurate occupancy calculations, it is important to 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:
   
1. This endpoint is used to pull information from PriceLabs on the current state of associated data.
   
2. Information can be pulled for reservations, listings, and listing calendars.
   
3. This would not have a direct impact on the user’s data or experience, but can be used by the PMS to validate information, debug during integration development, or provide support to users of the established integration.
   
7. Rate Plans
   
1. Endpoint: /rate_plans
   
2. Mandatory: No
   
3. Prerequisite: /listings
   
4. Description:
   
1. If the listing has multiple rate plans, this endpoint can be called to add or update rate plans for the listing.
   
2. It is important to note that there should be only one default rate plan for each listing.
   
3. After calling this endpoint, it is mandatory to call the /calendar endpoint to update rates and availability for the default rate plan.
   
4. If the default rate plan is changed, then it is mandatory to call the /calendar endpoint for the new default rate plan.
   
   
5. Example Integration Flow
   
   For demonstration, we’ll  use an adhoc name ‘Fancy Rentals’ as a PMS integrating with PriceLabs. Once Fancy Rentals receives the Integration token and Integration 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.  Fancy Rentals should store the token and regenerate the token via this endpoint if needed. If the PMS URLs aren't set, subsequent APIs may fail. For token regeneration, “regenerate_token” = true, should be sent in the /integration request.
   
2. Whenever a user creates a new listing in Fancy Rentals and adds their rates and/or availability, Fancy Rentals should call /listings endpoint for new listings followed by /calendar call to send a minimum of 12 months and up to 2 years of rates and availability.
   
3. When the user updates the rates and availability of their listings in Fancy Rentals, they should call /calendar to update the same in PriceLabs.
   
4. When PriceLabs calls the calendar trigger URL with the listing Ids, Fancy Rentals should call /calendar with a full refresh of rates and availability for those listings.
   
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 (configured by Fancy Rentals via /integration endpoint) 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 receives new reservations or updates to existing reservations or cancellations from users/channels, they should call the /reservations endpoint to send the reservation details to PriceLabs.  Since reservations /cancellations affect availability, follow with /calendar to update rates/availability.

Certification

1. The PMS should verify their integration with  our certification checklist (below).
   https://docs.google.com/spreadsheets/d/1nSzDMLMneX3Byukieo9CYhbXksYIL_NfT87tmBA5aP4/edit?   usp=sharing
2.  The PMS team should share some information regarding the integration along with the marketing information. The details can be found in the certification checklist link shared above.
   
3. The checklist also consists of  verification tests to make sure that the API flow is implemented correctly
   
1. Either run by PriceLabs using a test account on the PMS, OR
   
2. By  the PMS team and PriceLabs team over a joint pre-scheduled call.
   

Go-Live

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.
   

Post-Integration

1. Integration release and announcement across marketing channels (social media handles, partnership webpage, etc.).
   
2. Any potential co-marketing activities.