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 is Ocp-Apim-Subscription-Key which 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]" in authorization header.
- Token can be refreshed and revoked with dedicated methods

2. Get journey fares for selected search options

GET /fares

Request parameters

- limits for adults and children numbers - GET /booking-limits/passengers
- railcards - GET /railcards
- discountCategoryId - GET /discount-categories
- currencyIsoCode - GET /currencies
- tmcCompanyAccountId and tmcCompanyClientId for TMC bookings - GET /companies/managed-clients

3. Choose a fare and create an order with it

POST /orders

Request body parameters

- FareId - use selected Fares/Id return 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 - use discountCategoryId submitted in step 2
- CompanyAccountId and CompanyClientId for TMC bookings - use tmcCompanyAccountId and tmcCompanyClientId from step 2 respectively
- Passenger data - needs to be provided as an input from the end user

4. Get survey questions

GET /survey-questions

Request parameters

- companyAccountId and companyClientId - the same value as used in the order creation step

5. Submit answers for questions

PUT /orders/{token}/answers

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