The HHR Ticketing System OTA API provides a standardized way for Online Travel Agencies (OTAs) and partners to integrate with Saudi Arabia Railway’s Haramain High Speed Railway booking system.

Getting Started

The API follows the OpenTravel Alliance (OTA) standards, adapted to JSON, and exposes endpoints that allow partners to:

• Search train availability and lowest fares (one-way and round-trip)

• Retrieve pricing details before booking

• Create and confirm bookings

• Read and manage existing reservations

• Cancel bookings

• Access calendar-based availability

Key Features

• JSON Requests & Responses: All interactions use application/json.

• OTA-Compliant Schema: Parameters and objects follow OTA standard structures.

• Environment Separation: Pre-Production (testing/staging) and Production endpoints are provided.

• Authentication: HTTP Basic Authentication (username + password) or API Keys access via each request in the headers.

• Versioning: Current API version is 2.001.

Stations

Use the following station codes in all API requests:

💡 Tip:
Use the GetRoutesRQ endpoint once to retrieve all available station codes and become familiar with them before building production-level integrations.

Business Flow

This diagram illustrates the API call sequence for searching available trains, creating a reservation, intermediate steps required to issue tickets, modify an existing booking, cancel a booking, and resend or download passengers tickets.

Regular Booking

This flow is the standard and the most simple flow to create a regular booking for indivisuals (less than 11 passengers):

Here, in this section we will explain how you can create a regular booking by using the following flow:

1.AirLowFareSearch:

This request is responsible for fetching the available trains in our booking system In this request we will send the required searching crieteria from the user inputs including the origin, destination, train date, class, and segments.

There are some points need be highlited you need to know about it for the search request so you can get the most use of the request:

• The request can be used for (oneway) and (round trips) searching requests, if you used one object inside originDestinationInformation list including origin, destination, and date this automticly will consider it as oneway trip results.

• for Round-trips just add an additional object inside the list which will be two objects inside the originDestinationInformation list with the return train to getting the availiable trains in these two selected dates.

• You can include more than one class in one request to get all trains for the both classes on one response.

Endpoints

These are the following endpoints for accessing our endpints in the two environments (Pre and Prod):

Test Endpoints

Production Endpoints

Authentication

API KEY

The API key should be attached to the HTTP request as X-API-Key HTTP header.

Never deploy your key in client-side like browsers or mobile apps as it allows malicious users to take that key and make requests on your behalf.

Request

1
curl -X POST \
2
    {base_url} \
3
    -H 'x-api-key: {api_key}' \
4
    -H 'local-name: {local_name}' \

Code Lists

Our code list determine the unique class code for each booking class:

Booking Class

Passengers type

We have only three passenger profiles as stated bellow:

Document Type

This table stating the approved and accepted types of passengers documents via the API requests: