reservations-eapi icon

reservations-eapi

2.1.x
(0 reviews)

There will be three main categories of Reservation resources, supported by reference data:

  1. Query availability
  2. Make or amend a booking
  3. Retrieve coach details
  4. Reference data

Each of these categories may contain one or more resources as determined by the requirements and underlying RARS platform capabilities.

Currently only the availability endpoint has a v2 variant in Production. Other endpoints will be added as and when their v2 variant gets released to Production.

NOTE: for version 2 and above of this API

  • the domain of the Reservations API is different to that of v1.
  • the client_id and User-Agent headers are mandatory, whereas they were optional in v1
  • when there is a request body (e.g. POST request), the Content-Type header is mandatory and must be set to application/json
  • if specified, the x-correlation-cust-id header must be less than 100 characters
Query Availability
  • /v2/availability

This resource allows consumers to request availability of products on services. The availability resource allows consumers to request availability for one more products against one or more journeys(1) to determine whether they are available and to retrieve the tariff codes needed to make a booking. This API also allows users to optionally specify a priority sequence for products, which has the effect of limiting the response to only the highest priority available product(s).

(1) subject to limits specified in RDG Standard RSPS5210

Make or amend a booking
  • /bookings

This resource allows consumers to make a provisional booking. It enables consumers to supply customer, journey, product and optionally seat information in order to provisionally reserve a seat (or berth if applicable). Once provisionally reserved the seat will be held for that customer for a configurable period of time (currently 30 mins). Consumers have to confirm the booking (see below) within that time window otherwise the provisional booking will be automatically cancelled (expire).

  • Last name and phone number must be provided for sleeper bookings
  • Passenger IDs must be sequential and must start with passenger_1 (e.g., passenger_1, passenger_2, etc.)
  • /bookings/{bookingReference}

This resource allows consumers to recall a provisional or confirmed booking using the unique booking reference assigned to it by the reservations service

  • /bookings/{bookingReference}/status

This resource allows consumers to update a booking's status. Possible options are:

  • Confirm - this will confirm a provisional booking (i.e. the booking will not expire and must be explicitly cancelled to be released)
  • Cancel - this will cancel a booking and can be used for either provisional or confirmed bookings
  • Revert - this will back out changes made to a confirmed booking

Note: It is best practice to cancel a provisional booking if it is known that it will not be taken up, rather than allowing it to expire, as this will free up the held seats for other passengers to potentially book.

  • /bookings/{bookingReference}/seats

This resource allows consumers to update a seat associated to a reservation, subject to availability. This can be done before or after a provisional booking is confirmed.

  • /bookings/{bookingReference}/customer

This resource allows consumers to manage a Customer's details, such as name, email address, phone number, etc. A Customer is the 'owner' of a booking as distinct from passengers which are those who are actually travelling. In the majority of cases the Customer will be one of the passenger's but this may not always be the case - for example a corporate booking may be made by a representative of a business (e.g. a PA) as the Customer, for one or more employees to travel as the Passengers. Because these details contain personably identifiable information they will be hidden/masked in certain circumstances for GDPR compliance purposes.

  • /bookings/{bookingReference}/passengers

This resources allows consumers to manage passenger details, such as name, email address, phone number, etc. It also allows additional passengers to be added to an existing booking. Because these details contain personably identifiable information they will be hidden/masked in certain circumstances for GDPR compliance purposes.

  • /bookings/{bookingReference}/passengers/cancel

This resource allows consumers to cancel (remove) one or more passengers from an existing booking

To cancel passenger(s) the system requires the passenger identifier (uuid), which can be found in the booking:

  • data->passengers->uuid

As part of this call, the system will blank out the requested passenger details following successful cancellation of the passenger and will be recorded as a change to the booking.

  • /bookings/{bookingReference}/notes

This resource allows consumers to add free text notes to a booking. These notes have no functional impact and can be used to record any reasonable information relating to a booking which can not be applied to an existing field. Because these notes may contain personably identifiable information they will be hidden/masked in certain circumstances for GDPR compliance purposes.

  • /bookings/{bookingReference}/legs

This resources allows consumers to add one or more legs and/or product items to an existing booking

  • /bookings/{bookingReference}/legs/cancel

This resources allows consumers to cancel (remove) one or more legs from an existing booking

To cancel leg(s) the system requires the leg identifier (uuid), which can be found in the booking:

  • data->outboundBookingTariffLegs->uuid
  • data->inboundBookingTariffLegs->uuid
  • /bookings/{bookingReference}/legs/productItems/cancel

This resources allows consumers to cancel one or more seat product items from an existing booking

To cancel product item(s) the system requires the product item identifier (itemRef), which can be found in the booking:

  • data->outboundBookingTariffLegs->requiredProducts->itemRef
  • data->inboundBookingTariffLegs->requiredProducts->itemRef

(There is also an itemRef for additional products, however, additional products is intended for future use)

  • data->outboundBookingTariffLegs->additionalProducts->itemRef
  • data->inboundBookingTariffLegs->additionalProducts->itemRef

Although there is a uuid for a product item, the product item cancel resource requires the itemRef and not uuid, as specified above

  • /bookings/{bookingReference}/utn or /bookings/{bookingReference}/rbr

These resources allow consumers to add or update the Unique Ticket Number or Retailer Ticket Reference. These can be added when creating a provisional booking, or by using these resources consumers can add or change them at a later time.

  • /bookings/{bookingReference}/rebooking

This resource allows consumers to change the booked service(s) and/or product(s)

To perform a rebooking the system requires the product item identifier (uuid), which can be found in the booking:

  • data->outboundBookingTariffLegs->requiredProducts->uuid
  • data->inboundBookingTariffLegs->requiredProducts->uuid

Although there is an itemRef for a product item, the rebooking resource requires the uuid and not itemRef, as specified above

  • /bookings/references

This resource allows consumers to recall a booking reference using a unique identifier assigned to it by the booking owner. Two different references can be used, subject to them being recorded against a booking:

  • Unique Ticket Reference (UTN) - this will allow consumers to recall a reservation using a barcode UTN.
  • Retailer Booking Reference (RBR) - this will allow consumers to recall a booking using a their own reference
  • /bookings/{rsid}/{serviceOriginDate}/{boardLocation}/{alightLocation}/{coachId}/{seatId}

This resource allows consumers to recall a booking reference applicable to a specified seat and calling points. This may be used, for example, to recall a booking reference for a Customer who knows which seat they are booked in but doesn't know their reference. A consumer would still need the usual permissions to recall or amend a booking once the reference has been retrieved.

  • /bookings/{rsid}/tickets/{serviceOriginDate}/{boardLocation}/{alightLocation}/{coachId}/{seatId}

This resource allows consumers to retrieve a ticket reference for a specified Service, Origin, Destination, Coach and Seat. This may be used to find a ticket reference number for a particular seat on a specified origin and destination to validate a booking. This also allows for the validation history of the booking to be returned.

  • /bookings/{rsid}/tickets/{ticketReference}

This resource returns details such as boarding, alight location, and validations for a specific ticket for consumers to verify the current validation status of a ticket.

  • /bookings/validate

This resource allows the validation value of a reservation to be changed

  • /bookings/validate/revert

This resources allows a booking validation to be reverted to it's previous value from a value of RELEASE_REQUESTED

  • /bookings/booking

This resource allows consumers to attempt a booking without first checking for availability. If the requested product is fully available a provisional booking will be made, and if it isn’t, an error message will be returned. Consumers can also optionally request for the provisional booking to be confirmed.

It is the equivalent of the consumer doing the below separate API requests:

  • POST /availability to check availability
  • POST /bookings to make a provisional booking (using tariff code from availability response)
  • optionally, PUT /bookings/{bookingReference}/status to confirm booking (using bookingRef from make booking response)
Retrieve coach details
  • /service/{rsid}/coaches

This resource provides the full details of a service, including; the number of coaches and their sequence order, what seats are on each coach and their properties (e.g. plug socket available), and the booking status of each seat. The response also includes an image for each of the coaches along with dimensions of both the coach and the position and dimensions of seats within each coach so that these can be plotted on a suitable display.

  • /service/{rsid}/coaches/images

This resource is a subset of the coach layout resource; providing only the details, sequence and image of each coach on a service without the seat status or position/dimension information

  • /services/{rsid}/reports/passengers

This resource provides a list of passengers as well as seat reservation details on any given service for a particular train operating company

Reference data
  • /refdata/disabilityTypes

This resource allows consumers to request the latest list of disability types supported by the reservations service. Disability types can be submitted in booking requests and will impact on what seats may be booked (e.g. allowing seats specifically for passengers with wheelchairs).

  • /refdata/seatProperties

This resource allows consumers to request the latest list of seat properties supported by the reservations service. Seat property codes can be submitted in certain requests and returned by others. This reference data provides details of seat property codes and their associated descriptions for different carriers and time periods.

Security

The client_id, user-agent and content-type headers mentioned above have been added to v2 and above to improve security.

  • failure to specify the correct client_id will result in a 401 Unauthorised error
  • failure to specify a user-agent header will result in a 400 Invalid schema error
  • failure to specify the content-type as application/json, when required, will result in a 415 Unsupported Media Type error

Note: the user-agent value should include the name of system making the request and its version number (e.g. RDGRuntime/7.41.2)

The 100 character limit on x-correlation-cust-ids as also been added to improve security.

  • specifying an x-correlation-cust-id header with more than 100 characters will result in a 400 Invalid schema error

As shown in the examples, a Bearer token obtained from the RDG IAM API must always be sent in requests as the Authorization header.

  • failure to specify a valid Bearer token will result in a 401 Unauthorised error

Last update: 05-Dec-2025 15:49 ASSIST API Documentation Maintenance: 'reservations-eapi', Version 'v2', Page 'Home', Revision 'H'.

To request updates to this text please contact Neil Barkham.

Reviews