home > support > API > useful information for developers
Getting started with TourCMS API, part two (for Agents)
Make sure you have read part one.
Connecting to TourCMS to load your own tours & activities to sell? Read part two for Operators instead.
Common use-cases
If you are importing TourCMS products into your own database you will likely use List Tours to obtain a list of tours you can access, Show Tour to get the descriptions and images plus the rate types required for booking. Tour Departures will give you a list of all Departures for that product, including a detailed pricing breakdown for each rate on each date. Alternatively if you only wish to know which dates are available, Dates & Deals is faster.
If you are using TourCMS API to directly power the descriptions on your website you will likely use Search Tours to display listing pages, Show Tour for detail pages, Dates & Deals for an availability calendar. Alternatively consider adding Widgets to your page.
To place bookings in TourCMS please see the endpoints in our booking creation documentation. Alternatively there is a hosted booking solution which can be easily added to your website in a few moments.
Uniqueness within TourCMS
Unique product IDs
There are 3 core IDs that you will see returned in the data:
- Account ID - This is unique per TourCMS account. A single account can have multiple channels (each channel perhaps featuring different products, different language but same products or different prices but same products)
- Tour ID - Unique per Account ID but will be non-unique over multiple accounts
- Channel ID - Unique per channel
Hence if you care about removing duplicate tours, filter by a combination of Account ID / Tour ID.
You can filter by combination of Channel ID / Tour ID however if you are connected to the same TourCMS supplier account over multiple of their sales channels, you could have duplicate tours (e.g. an English version plus a French version)
To tell if it is the same tour from the same tour operator supplier, just in a different sales channel (e.g. perhaps with a different description language), check Account ID / Tour ID combination
Unique booking / customer IDs
There are 3 core IDs that you will see returned in the data:
- Account ID - This is unique per TourCMS account
- Customer ID - Unique per Account ID but will be non-unique over multiple accounts
- Booking ID - Unique per Account ID but will be non-unique over multiple accounts
Permissions
Permissions are set by the TourCMS account owner. All agents can see dates, prices, availability & create new bookings (via API and booking engine) and create enquiries (via API)
| Level | Description |
|---|---|
| 1 - Sell only | For advertisers
|
| 2 - Summary statistics | For agents/affiliates (DEFAULT)
|
| 3 - Full detail | For travel agents
Agents will will NOT see profit margin, costs or which suppliers have been used. |
i.e. Generally affiliates/marketing partners can see and sell product. Traditional Travel Agents can see bookings/enquiries.
Tour operators can see and alter customer / booking data
Seeing no data
- You can only see data from TourCMS accounts you are connected to. The onus is on the TourCMS account to give permission for you to see their data (perhaps after a commercial conversation)
- The API will normally only return data from TourCMS accounts that are paying (i.e. not free trial accounts) and are in good standing
Testing
- Inside the Marketplace agent login is a test harness to easily review responses to various XML calls
- The Marketplace agent login also has an API log so you can review recently made API requests and their responses as well as failure reasons
Product prices
The majority of API calls give you RETAIL (sale) prices. These can be shown directly to consumers
If you (as a travel agent) are working on commission OR net rates, the RETAIL prices will carry through the booking howevery your BALANCE OWING will take into account your commission or your agreed net rate. i.e. you will pay less than the retail price at point of paying
If you want to know what the net rates will be ahead of time, they can be found via the Show Tour Departures API call.
If you are working with some suppliers on commission and some on net rates, TourCMS will work this out for you automatically
API checklist
TourCMS do NOT mandate that we ratify or check your API integration - however - for some larger projects we do. This is what we will check
| 1 | Commercially sensitive data Net rates (i.e. commercial rates sold by a supplier and given to a travel agent) should never be exposed to customers Likewise, suppliers will give you average transaction size, click to book ratio etc. This should not be exposed to customers either |
| 2 | Quality control All tours in the TourCMS API have a minimum amount of data completed; so you can be sure products have base descriptions, geolocation, at least one image etc. Additional quality control is available to allow agents/affiliate to only feature tours that meet or exceed our Content Quality Guidelines including large image sizes and improved descriptions. Quality control can be used on a per API request basis, however we would recommend agents/affiliates switch on quality control inside their TourCMS control panel, ensuring quality control is in place automatically wherever available. |
| 3 | Hotel pickup points Ensure that hotel pickups are added at point of booking. It is possible to create bookings without hotel pickups but generally hotel pickup selection should be shown and handled. UI design notes Hotel pickups can be time sensitive - e.g. a hotel may be on a route for a morning tour but not an afternoon tour. This is why pickups are on the check availability API You know the time of the pickup (e.g. 10:00 or 14:00) - don't let the customer pick the 14:00 for a 11:00 tour start time Some tours have freetext "on request" hotel pickup capabilities. Check if this needs to be supported in your UI. |
| 4 | Display the date "note" Particularly when offering clients the ability to choose between various components available on a certain date the start/end date, start/end time is NOT sufficient to distinguish between all trips. The "note" can often be vital (e.g. could be zone information for a transfer, or a specific language that the tour is being run in). User interfaces for selecting between the available components should at a minimum show dates, times and "note" field where they differ between the components returned. |
| 5 | Total sale price may not be total of all the components There can be booking fees. There can be discounts for adding multiple components to the same basket. Check the value that comes back from booking start - rather than adding individual component sale prices. |
| 6 | Airport transfer information collected For product type 2 - Transport/Transfer - please collect the following information: Mandatory (most of the time!) Airline/Train name Flight/Train number Arrival Time Hotel name Consider adding Origin Destination Hotel address Greeting board details Luggage (e.g. Skis) This should be sent through in the note, on the component, in booking_start as follows: |
| 7 | Total customers Ensure that the correct total_customers is sent to booking start. If you don't know how many total customers you have, if you have a booking including one tour with 4 people & another tour with 3 people our general advice is to send 4 not 7 as the total_customers number. |
| 8 | API caching If calling the API in live time - that - as far as possible - API requests for tour search, details & dates/prices are cached (e.g. for 10 minutes). (Booking should always be done on live API calls though). Further information on caching |
| 9 | Agent reference On booking start and IF you are making a booking in a 3rd party system outside of TourCMS, please send the 3rd party system booking reference to TourCMS as agent_ref. Additionally, it is helpful if you preceed with your service name e.g. GLOBALOTA-123456. Define your service name as you like (we know the booking was made by you via other tracking). You MAY just have a booking reference, no service name, but it is preferable to have a service name. This agent reference, apart from being used for vouchers (see below) is helpful to tour operators to manually reconcile bookings between your system and TourCMS, if necessary IF you are only making the booking in TourCMS (and not your own system simultaneously) you may leave agent_ref blank |
| 10 | Voucher bar codes Please read and ensure you implement our guidance on vouchers and barcodes. |
| 11 | Your own email notifications (to supplier) If you are an Online Travel Agent (OTA), you send email notifications to the supplier (TourCMS powered tour operator) telling them about their new booking. Unless otherwise agreed with the supplier, please continue to send your email notifications even if you are also sending the booking via our TourCMS API (Many will ask you to turns your email notifications off, but best to wait for them to tell you, rather than assuming). The email address to send to is email_customer from Show Channel. |
| 12 | Defaulting next bookable date on a single tour page On a single tour page, when you are showing an available date calendar (probably informed by Dates & Deals)), default the next bookable date to next_bookable_date from Show Tour API rather than the first date in the dates & deals API. The next bookable date from tour show updates quicker than the dates & deals API (which is heavily cached), so this will be a more accurate approach |
| 13 | Supplier sign off to go live YOU MUST contact any supplier before you turn on for bookings and wait for their sign off / agreement to go live Specifically, please do not go live on a Friday. |
Questions?
Please do contact us.