---
title: "Match supplier rooms to a reference catalog"
method: POST
path: "/rooms/match"
tags: ["Room Match"]
---

# Match supplier rooms to a reference catalog

`POST /rooms/match`

## Request

- Base URL: `https://api.liteapi.travel/v3.0`
- URL: `https://api.liteapi.travel/v3.0/rooms/match`
- Auth: API key in header `X-API-Key`

**What it does:** For each supplier room, returns the best **reference room** match with confidence scores and ranked alternatives.

**Workflow role:** Optional **step 0** — quick sync scoring before async hotel jobs.

**Use when:** You need an **immediate** answer with `suppliers`. Either send `references` yourself, **or** omit `references` and set **`hotelId`** so the service resolves the catalog (`room_mapping_catalog` → LiteAPI data API; your references win if supplied; max 500 rooms).

**Do not use when:** You need persisted mappings, audit reasons, or room attributes — use `POST /rooms/match/async`. Not for clustering without a catalog — use `POST /rooms/group`.

**If `references` is omitted:** missing `hotelId` or unresolvable catalog → **400**; Redis or data API failure → **500**; suppliers×references over upstream cap → **413** when configured.

Details, examples, limits, and result codes: **Implementation Workflow** (doc page: `implementation-workflow`).

## Request body

- union
  - object
    - `hotelId` string, nullable: Hotel ID used to resolve the reference catalog when `references` is omitted. Required in that case; echoed in the response.
    - `chunkKey` string, nullable: Batch/chunk ID for large jobs
    - `threshold` number: Minimum confidence score for a positive match
    - `topK` integer: Number of ranked candidates returned per supplier
    - `references` ReferenceRoom[], required: Optional. Allowed mapping targets (the catalog). Omit or send empty to resolve the hotel catalog from `room_mapping_catalog:{hotelId}` (dispatcher-owned, read-only here), then the LiteAPI data API. Caller-supplied rooms win. Resolved catalogs are capped upstream (default 500) and never truncated; `hotelId` is required when this is omitted.
      - `id` union, required: Reference room identifier
        - string
        - integer
      - `name` string, required: Reference room title
    - `suppliers` SupplierRoom[], required: Supplier rooms to map
      - `i` integer, required: Supplier row index (stable within the request)
      - `name` string, required: Supplier room title
  - object
    - `hotelId` string, nullable, required: Hotel ID used to resolve the reference catalog when `references` is omitted. Required in that case; echoed in the response.
    - `chunkKey` string, nullable: Batch/chunk ID for large jobs
    - `threshold` number: Minimum confidence score for a positive match
    - `topK` integer: Number of ranked candidates returned per supplier
    - `references` ReferenceRoom[]: Optional. Allowed mapping targets (the catalog). Omit or send empty to resolve the hotel catalog from `room_mapping_catalog:{hotelId}` (dispatcher-owned, read-only here), then the LiteAPI data API. Caller-supplied rooms win. Resolved catalogs are capped upstream (default 500) and never truncated; `hotelId` is required when this is omitted.
      - `id` union, required: Reference room identifier
        - string
        - integer
      - `name` string, required: Reference room title
    - `suppliers` SupplierRoom[], required: Supplier rooms to map
      - `i` integer, required: Supplier row index (stable within the request)
      - `name` string, required: Supplier room title

## Response `200`

OK

- object
  - `data` object
    - `hotelId` string, nullable
    - `results` RoomMatchResult[]
      - `i` integer: Supplier index from the request
      - `name` string: Supplier room name
      - `status` 'mapped' | 'not_mapped': Whether a match was selected
      - `selected` MatchCandidate
        - `id` union: Reference room id
          - string
          - integer
        - `name` string: Reference room name
        - `scoreCalibrated` number: Confidence score between 0 and 1
        - `predictedLabel` integer: 1 if the candidate is a positive match at the decision threshold, otherwise 0
      - `candidates` MatchCandidate[]: Ranked candidate matches
        - `id` union: Reference room id
          - string
          - integer
        - `name` string: Reference room name
        - `scoreCalibrated` number: Confidence score between 0 and 1
        - `predictedLabel` integer: 1 if the candidate is a positive match at the decision threshold, otherwise 0

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `500`: Internal Server Error

---

[API](https://skmtc.dev/liteapi/apis/api-mapping.md) - [All operations](https://skmtc.dev/liteapi/apis/api-mapping/llms.txt) - [OpenAPI document](https://skmtc.dev/liteapi/apis/api-mapping/revisions/82f8d27a93af?raw)