Reference Data

Access platform-managed reference catalogs including transportation modes, room categories, product types, countries, and regions.

Overview

The Reference Data API provides access to platform-managed catalogs and static reference data that are centrally maintained and replicated across all regions for low-latency reads. These endpoints return read-only reference data that is globally consistent.

Available Reference Types

200 OK

{
  "items": [
    {
      "type": "transportation_mode",
      "name": "Transportation Modes",
      "description": "Modes of transportation (e.g., flight, train, bus, car)",
      "endpoint": "/v1/ref/transportation-modes"
    },
    {
      "type": "room_category",
      "name": "Room Categories",
      "description": "Hotel and accommodation room categories",
      "endpoint": "/v1/ref/room-categories"
    },
    {
      "type": "product_type",
      "name": "Product Types",
      "description": "Available product types (tour, experience, package, accommodation, cruise)",
      "endpoint": "/v1/ref/product-types"
    },
    {
      "type": "country",
      "name": "Countries",
      "description": "List of countries with regions",
      "endpoint": "/v1/ref/countries"
    },
    {
      "type": "region",
      "name": "Regions",
      "description": "Accounting regions",
      "endpoint": "/v1/ref/regions"
    }
  ]
}

Authentication

Most reference data endpoints are public read endpoints and do not require authentication. However, write operations (POST, PUT, DELETE) for managed catalogs (transportation modes, room categories) require the X-Admin-Service-Key header for platform administrator access.

Endpoints

Platform-Managed Catalogs

These catalogs are managed by platform administrators and automatically replicated across regions:

• Transportation Modes - List all transportation modes
• Get Transportation Mode - Get a specific transportation mode
• Room Categories - List all room categories
• Get Room Category - Get a specific room category
• Product Types - List all available product types

Static Reference Data

These endpoints return static reference data:

• Countries - List all countries with regions
• Regions - List accounting regions

Data Consistency

Managed catalogs (transportation modes, room categories) are maintained in a central control plane database and automatically replicated to regional mirrors. All read operations query the regional mirrors for low latency, while write operations are gated and trigger automatic replication.

Notes

• All managed catalog endpoints return only active records by default (isActive: true)
• Records are sorted by displayOrder (ascending) and then by name (ascending)
• Soft-deleted records (inactive) are excluded from public read endpoints
• IDs are UUID v7 format for global uniqueness and temporal ordering