-
Notifications
You must be signed in to change notification settings - Fork 4
Integration flow for Partners
This document is addressed towards our integration partners. Quick links to navigate:
- APIs walk through and live Headout site parallels
- Product flow with integration suggestion to partners
- Major FAQs
Sample url: https://www.headout.com/api/v1/product/listing/list-by/city?cityCode=DUBAI
Documentation link: https://github.com/headout/api-docs/blob/master/apis/product.md#GET-/product/listing/list-by/city
Corresponding model link: https://github.com/headout/api-docs/blob/master/object-models/product-models.md#product-listing
This API returns list of all Headout products in a particular city. A parallel in headout live website can be found here where we list products in Dubai and paginate the product results. An item in product list response is a subset of product model with basic information about a single product. Note the cityCode param in the url. This param can accept all headout live city codes (Ex: DUBAI, ABU_DHABI, NEW_YORK). Also note that pricing information is not a part of this API.
Future additions:
- We will add a new API soon which will give out list of all Headout live cities and their info.
Sample url: https://www.headout.com/api/v1/product/get/1866
Documentation link: https://github.com/headout/api-docs/blob/master/apis/product.md#GET-/product/get/%7Bproduct_id%7D
Corresponding Model link: https://github.com/headout/api-docs/blob/master/object-models/product-models.md
This API returns all details of a Headout product. Find the link to Headout live product parallel here. All the content visible in the product page in our site comes from the product API (this includes images, text description, faqs, reviews etc). Product api contains the details of all variants of a single product. Each variant gives different experience for end users and inventory/pricing details needs to be fetched for all variants separately. Ex: Given Sample url response has three variants 'Skip the Line' (id: 2636), 'Sunrise' (id: 2637), 'General Admission' (id: 2638). Each variant has its own inventory and pricing types. Refer the details here Each variant has its own set of input fields that needs to be filled out by user for a successful checkout. User responses for all input fields needs to be sent as part of the booking request. Refer more details here. Note that pricing and inventory information is not a part of this API.
Sample url: https://www.headout.com/api/v1/inventory/list-by/variant?variantId=2636
Documentation link: https://github.com/headout/api-docs/blob/master/apis/inventory-pricing.md
Corresponding model link: https://github.com/headout/api-docs/blob/master/object-models/inventory-pricing-models.md
This API returns inventory details of a variant. Major verticals of inventory are Date and Time. Once fetched for all variants, data from inventory API can be used to give out a product flow similar to the one you can find in our Headout web app. Checkout the product flow post content page here.
By default we assume you are interested only about inventory for next 30 days. You can change this by supplying us startDateTime and endDateTime params in the api call. Note that inventory becomes highly volatile (both from pricing and availability standpoint) (We maintain active inventory of ~90days for each product). Inventory must be actively refreshed for all variants to maintain pricing and availability accuracy. We have different types of inventory and pricing constructs which might dictate the user checkout experience. You can go through the differences here
Sample url - step 1: https://www.headout.com/api/v1/booking/create Sample url - step 2:
Documentation url: https://github.com/headout/api-docs/blob/master/apis/booking.md
Corresponding model link: https://github.com/headout/api-docs/blob/master/object-models/booking-models.md
These are the two apis for a successful booking to happen. Step 1 api to be used to confirm if we can fulfill the booking. Step 2 api to be used to confirm that user is charged from your end and we can trigger post purchase steps from our end. If there is a timout or api response issues for step 2, you can keep on requesting the step 2 url until you get a success message (from our end, we only trigger post purchase steps only once)
Product flow starts with city level decisions. For now, we assume that your application, at any given point, shows products of only one city. Assuming that the user selects a city in your application, you can list Headout products that are live in the selected city (Ex: Headout product list page). (Api to fetch Headout live cities is WIP).
City codes for major cities:
- New York - NEW_YORK
- Dubai - DUBAI
- Abu Dhabi - ABU_DHABI
Products in a particular city can be fetched using our product list api. The order of products in the api is decided based on best selling and trending patterns. We advise our partners to retain the order of products.
Note: If your application shows products of different cities at once (Ex: a portal which lists Dubai and Abu Dhabi products together), let us know so that we can provision another product list api which gives out list of products from any number of cites together. This can be done using two separate fetches from our product list api too but the order of products post the merge needs to be handled yourselves.
Once a user selects a product, user is taken to a product page (Ex: Headout live page - https://www.headout.com/tour/1866). The product page can make use of content from our product content api to showcase and explain the product to the end customer.
Once a user selects a product, we expect three decisions from the user before going to the checkout page.
- Variant of the experience
- Date of the experience
- Time of the experience
Internally these are represented by the inventory id from the inventory fetch api of a particular variant.
UX flow can be designed with any combinations of above. Headout live site of our major products follows below paradigm:
- Date of the product needs to be selected first. This date is the possible date user can experience (A merge of inventory details of all variants of a particular product)
- Variant and time - Once a user selects a date, we showcase all variants and time combinations for that particular date together. Another combination is to get user to select variant (or time) of possible variants (or times) for the selected data before proceeding with the third option.
A sample flow can be found here
Once the user selects a product-inventory(variant-date-time) unit, we proceed to ask user for number of tickets he wants to purchase. Note that the number of possible tickets customer can purchase need to be capped from the inventory data. Inventory can be of two types - per-person and per-group. In a per-person type, we have different profiles or ticket types that user can purchase (typical being Adult, Child etc). In a per-group type, user need to purchase bulk tickets of single type. Majority of Headout products (~95%) follow per-person pricing. We advise partners to integrate per-person products into their system first (i.e, manually filter our per-group products from product list api) and include per-group products in subsequent version.
Once user selects, product-inventory-pax we proceed to collect input from user as per input-fields requirement from the product fetch api. Email, Full name, Phone number are mandatory fields from Primary user that will always be in input-fields data of a product. (Note that primary user and email address are the ones which will be used to log the booking in our system and tickets are expected to be used by. Secondary users are other folks accompanying the primary user to the experience when pax > 1) It is advised to integrate input fields into the booking flow to avoid delay in ticket delivery to customers post booking. But partners can let us know if the integration for input fields needs to be standardised for version 1 rollout and we can provide a variant of booking api and product flow which doesn't use input fields as above.
Once user gives all checkout details, booking happens in two steps. Before user is charged, you need to do a POST request with the booking details as mentioned in documentation. A success response here implies that we are ready to fulfill this booking. There can be failures if the inventory is stale. (Proper error codes and their respective meaning + way to handle the error is a WIP. We will roll this out soon). If there is a timout or failure here, you can hit this api multiple times until you receive a successful response. (The itinerary id in the response needs to be stored). Once you get a successful response from step-1 api, you can charge your customer post which you can hit step-2 api with itinerary id so that we can mark it s a successful booking. A timout etc here should be fine since you can hit this api until you get a success message.
Additional APIs: Note that we don't support cancellation as of yet. Any cancellation requests from users will be handled by our support team. We are building a booking fetch api which will return all Headout bookings made from your end. This is a WIP
Auth keys will be sent out over email to our partners. If you are looking to integrate with us, write to [partnerships(at)headout(dot)com]([email protected]] or apiKey(at)headout(dot)com[[email protected]]
The auth keys are mainly used for booking apis. Other apis can be used without any auth (but we strongly suggest to send auth keys for all api calls). You can use test auth key for internal testing. All bookings made through prod key will be considered as official bookings. Refer here for proper integration.
Given that we provide a lot of products in a single city we advise caching our api responses for better user experience. Sample effective way of caching and usage.
- All product list api responses for a single city are fetched and saved (preserving the order) The refresh rate can be 1day. Lesser the better to capture last minute events
- Product content fetches are done for all products in the city and cached. Refresh rate can be 1day. Lesser the better to capture our live media and content changes
- Product inventory fetches are done for all products in the city for next 90 days. Refresh can be 5-10minutes. Lesser the better to capture inventory and pricing details properly. If user sees a stale price, booking fails from our end.
- When showcasing products to user, use the cached inventory data to filter out products. Primary filter is to remove products which doesn't have inventory. Any other filters like date range, date, time range etc can be applied and products that doesn't match the criteria can be removed using cached inventory data.
You can reach out to us through emailing/calling tech POC. We use slack for internal communication as well as external partner communication. Give us email id of POC from your end and we will invite you to our partners slack channel. We prefer this since the communication is fast here.
Right now all prices that are sent in inventory and pricing APIs are the final prices to be charged to customer. We are building functionality to send the retail price along with the final price. You can use this to show the discounts etc to the customer. (WIP)