---
title: "Submit an async room mapping job"
method: POST
path: "/rooms/match/async"
tags: ["Room Match"]
---

# Submit an async room mapping job

`POST /rooms/match/async`

## Request

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

**What it does:** Starts a **background mapping job** for one hotel (`jobId` to poll).

**Workflow role:** **Step 1** — create or refresh hotel mappings.

**Use when:** Hotel onboarding, catalog refresh, or sending trusted **attributes** (`supplierRooms`, optional `referenceRooms`, `attributeDetail`).

**Do not use when:** You only need instant sync scores — use `POST /rooms/match`.

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

## Request body

- union
  - object
    - `hotelId` string, required: Non-empty hotel identifier
    - `referenceRooms` object[]: Optional. Allowed mapping targets (the catalog). Omit or send empty to score against our hotel catalog, which the service resolves automatically. When supplied, the caller's list wins. Rejected above 500 rooms; the same limit applies to the catalog resolved on your behalf. Attributes are optional per room.
      - `id` integer, required: Reference room id
      - `name` string, required: Reference room title
      - `attributes` RoomAttributes: Optional structured evidence about a room. Omitted fields mean the source did not state them, never that the room lacks them. Normalised on submit: enum values are lower-cased and trimmed, m2/m² are folded into sqm, and string lists are deduplicated. Unknown structure, bedRelation or size.unit values, negative counts and non-positive sizes return 400. At most 4 KiB per room's attributes and 256 KiB across a list.
        - `structure` 'room' | 'suite' | 'studio' | 'apartment' | 'villa' | 'penthouse': Room structure as stated by the source. Do not infer it from a marketing room name.
        - `tier` string: Commercial tier stated by the source (standard, premium, deluxe, ...).
        - `bedrooms` integer: Stated bedroom count for multi-room structures. 0 or omitted means not stated.
        - `beds` RoomBed[]: Stated bed configuration.
          - `type` string, required: Normalised bed type. Labels are canonicalised: 'Extra-large double bed (Super-king size)' becomes extra_large_double, 'Queen bed' becomes queen.
          - `label` string: Bed description as stated by the source.
          - `count` integer: Number of beds of this type.
          - `sizeCm` string: Stated width band.
        - `bedRelation` 'and' | 'or' | 'none': Whether the listed beds are all present (and), alternatives (or), or a single configuration (none).
        - `occupancy` object: Stated capacity.
          - `maxAdults` integer
          - `maxChildren` integer
          - `maxOccupancy` integer
        - `size` object: Stated floor area, normalised to square metres.
          - `value` number, required
          - `unit` 'sqm', required: Square metres. m2 and m² are folded into sqm on submit.
        - `views` string[]: Normalised view labels. 'City View' and 'city' converge on city.
        - `accessibility` string[]: Normalised accessibility features stated by the source (for example mobility_accessible, roll_in_shower). Never inferred from a room name.
        - `features` object: Only attributes the source stated as true or false; a missing key means unknown, not false. Informational, never gates a match.
        - `amenities` string[]: Optional amenity list for audit context. Informational; never gates a match.
        - `source` object: Provenance retained for auditability.
          - `roomTitle` string
          - `officialSiteRoomName` string
          - `rawSizeUnit` string
    - `roomNames` string[], required: Supplier room names to map. Blank entries are dropped and normalized duplicates are removed. Max 100 after deduplication. Ignored when `supplierRooms` is non-empty.
    - `supplierRooms` object[]: Attribute-bearing supplier rooms. When non-empty it replaces `roomNames`. Blank names are dropped and normalized duplicates removed; max 100 after deduplication. Sending attributes lets the audit treat our own catalog attributes as evidence on both sides.
      - `name` string, required: Supplier room name.
      - `attributes` RoomAttributes: Optional structured evidence about a room. Omitted fields mean the source did not state them, never that the room lacks them. Normalised on submit: enum values are lower-cased and trimmed, m2/m² are folded into sqm, and string lists are deduplicated. Unknown structure, bedRelation or size.unit values, negative counts and non-positive sizes return 400. At most 4 KiB per room's attributes and 256 KiB across a list.
        - `structure` 'room' | 'suite' | 'studio' | 'apartment' | 'villa' | 'penthouse': Room structure as stated by the source. Do not infer it from a marketing room name.
        - `tier` string: Commercial tier stated by the source (standard, premium, deluxe, ...).
        - `bedrooms` integer: Stated bedroom count for multi-room structures. 0 or omitted means not stated.
        - `beds` RoomBed[]: Stated bed configuration.
          - `type` string, required: Normalised bed type. Labels are canonicalised: 'Extra-large double bed (Super-king size)' becomes extra_large_double, 'Queen bed' becomes queen.
          - `label` string: Bed description as stated by the source.
          - `count` integer: Number of beds of this type.
          - `sizeCm` string: Stated width band.
        - `bedRelation` 'and' | 'or' | 'none': Whether the listed beds are all present (and), alternatives (or), or a single configuration (none).
        - `occupancy` object: Stated capacity.
          - `maxAdults` integer
          - `maxChildren` integer
          - `maxOccupancy` integer
        - `size` object: Stated floor area, normalised to square metres.
          - `value` number, required
          - `unit` 'sqm', required: Square metres. m2 and m² are folded into sqm on submit.
        - `views` string[]: Normalised view labels. 'City View' and 'city' converge on city.
        - `accessibility` string[]: Normalised accessibility features stated by the source (for example mobility_accessible, roll_in_shower). Never inferred from a room name.
        - `features` object: Only attributes the source stated as true or false; a missing key means unknown, not false. Informational, never gates a match.
        - `amenities` string[]: Optional amenity list for audit context. Informational; never gates a match.
        - `source` object: Provenance retained for auditability.
          - `roomTitle` string
          - `officialSiteRoomName` string
          - `rawSizeUnit` string
    - `attributeDetail` 'none' | 'summary' | 'full': How much attribute context the audit receives. `none` sends names only; `summary` (default) sends structure, tier, bedrooms, beds, bedRelation, occupancy, size, views and accessibility; `full` adds features, amenities and source. Applies to both supplier and reference attributes. The full request is always stored on the job.
  - object
    - `hotelId` string, required: Non-empty hotel identifier
    - `referenceRooms` object[]: Optional. Allowed mapping targets (the catalog). Omit or send empty to score against our hotel catalog, which the service resolves automatically. When supplied, the caller's list wins. Rejected above 500 rooms; the same limit applies to the catalog resolved on your behalf. Attributes are optional per room.
      - `id` integer, required: Reference room id
      - `name` string, required: Reference room title
      - `attributes` RoomAttributes: Optional structured evidence about a room. Omitted fields mean the source did not state them, never that the room lacks them. Normalised on submit: enum values are lower-cased and trimmed, m2/m² are folded into sqm, and string lists are deduplicated. Unknown structure, bedRelation or size.unit values, negative counts and non-positive sizes return 400. At most 4 KiB per room's attributes and 256 KiB across a list.
        - `structure` 'room' | 'suite' | 'studio' | 'apartment' | 'villa' | 'penthouse': Room structure as stated by the source. Do not infer it from a marketing room name.
        - `tier` string: Commercial tier stated by the source (standard, premium, deluxe, ...).
        - `bedrooms` integer: Stated bedroom count for multi-room structures. 0 or omitted means not stated.
        - `beds` RoomBed[]: Stated bed configuration.
          - `type` string, required: Normalised bed type. Labels are canonicalised: 'Extra-large double bed (Super-king size)' becomes extra_large_double, 'Queen bed' becomes queen.
          - `label` string: Bed description as stated by the source.
          - `count` integer: Number of beds of this type.
          - `sizeCm` string: Stated width band.
        - `bedRelation` 'and' | 'or' | 'none': Whether the listed beds are all present (and), alternatives (or), or a single configuration (none).
        - `occupancy` object: Stated capacity.
          - `maxAdults` integer
          - `maxChildren` integer
          - `maxOccupancy` integer
        - `size` object: Stated floor area, normalised to square metres.
          - `value` number, required
          - `unit` 'sqm', required: Square metres. m2 and m² are folded into sqm on submit.
        - `views` string[]: Normalised view labels. 'City View' and 'city' converge on city.
        - `accessibility` string[]: Normalised accessibility features stated by the source (for example mobility_accessible, roll_in_shower). Never inferred from a room name.
        - `features` object: Only attributes the source stated as true or false; a missing key means unknown, not false. Informational, never gates a match.
        - `amenities` string[]: Optional amenity list for audit context. Informational; never gates a match.
        - `source` object: Provenance retained for auditability.
          - `roomTitle` string
          - `officialSiteRoomName` string
          - `rawSizeUnit` string
    - `roomNames` string[]: Supplier room names to map. Blank entries are dropped and normalized duplicates are removed. Max 100 after deduplication. Ignored when `supplierRooms` is non-empty.
    - `supplierRooms` object[], required: Attribute-bearing supplier rooms. When non-empty it replaces `roomNames`. Blank names are dropped and normalized duplicates removed; max 100 after deduplication. Sending attributes lets the audit treat our own catalog attributes as evidence on both sides.
      - `name` string, required: Supplier room name.
      - `attributes` RoomAttributes: Optional structured evidence about a room. Omitted fields mean the source did not state them, never that the room lacks them. Normalised on submit: enum values are lower-cased and trimmed, m2/m² are folded into sqm, and string lists are deduplicated. Unknown structure, bedRelation or size.unit values, negative counts and non-positive sizes return 400. At most 4 KiB per room's attributes and 256 KiB across a list.
        - `structure` 'room' | 'suite' | 'studio' | 'apartment' | 'villa' | 'penthouse': Room structure as stated by the source. Do not infer it from a marketing room name.
        - `tier` string: Commercial tier stated by the source (standard, premium, deluxe, ...).
        - `bedrooms` integer: Stated bedroom count for multi-room structures. 0 or omitted means not stated.
        - `beds` RoomBed[]: Stated bed configuration.
          - `type` string, required: Normalised bed type. Labels are canonicalised: 'Extra-large double bed (Super-king size)' becomes extra_large_double, 'Queen bed' becomes queen.
          - `label` string: Bed description as stated by the source.
          - `count` integer: Number of beds of this type.
          - `sizeCm` string: Stated width band.
        - `bedRelation` 'and' | 'or' | 'none': Whether the listed beds are all present (and), alternatives (or), or a single configuration (none).
        - `occupancy` object: Stated capacity.
          - `maxAdults` integer
          - `maxChildren` integer
          - `maxOccupancy` integer
        - `size` object: Stated floor area, normalised to square metres.
          - `value` number, required
          - `unit` 'sqm', required: Square metres. m2 and m² are folded into sqm on submit.
        - `views` string[]: Normalised view labels. 'City View' and 'city' converge on city.
        - `accessibility` string[]: Normalised accessibility features stated by the source (for example mobility_accessible, roll_in_shower). Never inferred from a room name.
        - `features` object: Only attributes the source stated as true or false; a missing key means unknown, not false. Informational, never gates a match.
        - `amenities` string[]: Optional amenity list for audit context. Informational; never gates a match.
        - `source` object: Provenance retained for auditability.
          - `roomTitle` string
          - `officialSiteRoomName` string
          - `rawSizeUnit` string
    - `attributeDetail` 'none' | 'summary' | 'full': How much attribute context the audit receives. `none` sends names only; `summary` (default) sends structure, tier, bedrooms, beds, bedRelation, occupancy, size, views and accessibility; `full` adds features, amenities and source. Applies to both supplier and reference attributes. The full request is always stored on the job.

## Response `202`

Accepted - job queued

- object
  - `data` object
    - `jobId` string, required
    - `status` string, required
    - `hotelId` string, required

## Other responses

- `400`: Bad Request - malformed JSON or validation failure. Also returned when `hotelId` is missing, when neither `roomNames` nor a non-empty `supplierRooms` is supplied, when `referenceRooms` is omitted and no catalog can be resolved for the hotel, when a room attribute is invalid (unknown `structure`, `bedRelation` or `size.unit`, negative counts, non-positive sizes, an empty `beds[].type`), when attributes exceed 4 KiB per room or 256 KiB per list, when `attributeDetail` is unknown, or when the supplied or automatically resolved catalog exceeds 500 rooms.
- `401`: Unauthorized
- `409`: Conflict - a deep-map job is already in flight for this hotel
- `500`: Internal Server Error. Also returned as `failed to resolve reference rooms` when `referenceRooms` was omitted and the hotel data API could not be reached.

---

[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)