Steps to integrate

1. Pre-Integration
   

1. Generating credentials
   

1. The following credentials are required to access PriceLabs IAPI:
   
   

                X-INTEGRATION-NAME

                X-INTEGRATION-TOKEN
   
   

   Kindly reach out to support@pricelabs.co in order to get the credentials.
   
   
2. Our integration team will be in touch to share the relevant credentials that can be used to access PriceLabs IAPI
   

2. Trying out and getting familiar with our end points using our Swagger
   

1. Once you receive the credentials, we recommend trying out and getting familiar with our API using our Swagger
   
2. The base URL for all API calls is available on the swagger.
   

2. Development and certification
   

1. 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 endpoint by the PMS, and X-INTEGRATION-NAME which 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 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.
      
      

   
   
2. 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.
   
   
   
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. 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)
   
   
4. 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:
   
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. 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.
   
2. 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.
   
   
   
   
3. 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:
   
1. 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.
   
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 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)
   
4. 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:
   
1. 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.
   
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 on sync
   

   URL. 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, 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:
   
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 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.
   
3. 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. 
   
4. 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:
   
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 your PMS to validate information, debug during integration creation, 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 exactly 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 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.
   
   
   
   
   

2. Certification
   

1. 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.
   
   
   

3. Go-Live
   

1. 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.
   
   

3. Post-Integration
   

1. Once the integration is live, our partnerships team will get in touch to co-ordinate on the following:
   
1. Integration release and announcement across various marketing channels (social media handles, partnership webpage, etc.)  
   
2. ​Any potential co-marketing activities