Workflow for booking a ticket using the Heathrow Express API
The following steps show the Standard Booking Integration from planning a journey through to booking a ticket. The resources should be used in the sequence set out below. The illustration shows the interaction between a client, the API and message server through each step of the end-to-end booking process. This should be used as a reference when you are planning to build your first integration with our booking platform.
Our API section contains further information on the API methods with code samples in multiple languages.
To better understand the terms used in the description below please visit our glossary page.
1. Authenticate as a valid API user
API Management (APIM) layer
- Crucial header to be set in the request isOcp-Apim-Subscription-Keywhich will contain a key assigned to your subscription after you are successfully registered and subscribe to one of the Heathrow Express products.
- For information about test accounts to use during the authentication please refer to your subscription activation mail.
Application layer
- At the beginning the API client needs to get authenticated with the API user (different from the one used to sign-in to the Portal)
- To authenticate - please visit /connect/token
- Request body (please fill with the values received in your subscription activation mail):
username={app username}
&password={app user password}
&client_id={client id}
&client_secret={client secret}
&grant_type=password
&scope=openid+api
Using authorisation token
- Once obtained the authorisation token will be used in each subsequent request to the API.
- To use the token in API methods put "Bearer [token value]" inauthorizationheader.
- Token can be refreshed and revoked with dedicated methods
2. Get journey fares for selected search options
GET /fares
Request parameters
- limits foradultsandchildrennumbers - GET /booking-limits/passengers
-railcards- GET /railcards
-discountCategoryId- GET /discount-categories
-currencyIsoCode- GET /currencies
-tmcCompanyAccountIdandtmcCompanyClientIdfor TMC bookings - GET /companies/managed-clients
3. Choose a fare and create an order with it
POST /orders
Request body parameters
-FareId- use selectedFares/Idreturn parameter received in step 2 from /fares response
-Currency- GET /currencies
- Below parameters should only be applied if booking is made in the context of a Travel Management Company:
-DiscountCategoryId- usediscountCategoryIdsubmitted in step 2
-CompanyAccountIdandCompanyClientIdfor TMC bookings - usetmcCompanyAccountIdandtmcCompanyClientIdfrom step 2 respectively
-Passenger data- needs to be provided as an input from the end user
4. Get survey questions
Request parameters
-companyAccountIdandcompanyClientId- the same value as used in the order creation step
5. Submit answers for questions
Request parameters
-token- token obtained after creating the order in step 3
Request body parameters
-Answers/QuestionId- use identifiers returned by /survey-questions
-Answers/AnswerIds- use answer identifiers related to question chosen above returned by /survey-questions
-Answers/TextAnswer- free text value to be provided by the user
6. Confirm created order
PUT /orders/{token}/confirmation
Request parameters
-token- token obtained after creating the order in step 3
Request body parameters
- In request body an empty object needs to be passed "{}".
7. Pay for the order
POST /payments/onAccount
Request body parameters
-OrderAccessToken- token obtained after creating the order in step 3
-SmsPhoneNumber- value representing phone number to which SMS can be sent, provided manually by the user
-AcceptUpdateFeed- flag informing if the user accepts updates coming from Heathrow Express
8. Fulfilment
- Payment is the final step of the booking flow - once booking is ready an e-mail will be sent to the person who made the order with further details.
Standard Booking Integration
