> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mapping.travel/llms.txt
> Use this file to discover all available pages before exploring further.

# Search and Filter Hotel Mapping Results

> Filter and paginate individual hotel match results after a mapping job completes. Search by name, city, country, partner ID, reference ID, or supplier IDs.

After a mapping job reaches `COMPLETED` status, you can search through the individual hotel match results. The search endpoint lets you filter by hotel name, location, your own partner IDs, the matched reference hotel, or specific supplier IDs. Results are paginated and include match confidence scores, match methods, and supplier external IDs.

## Search endpoint

```
POST /api/v1/mapping/{mappingJobId}/results/search
```

All filters in the request body are optional. Omit any filter you don't need — null values are ignored.

### Request fields

| Field                     | Type           | Description                                                        |
| ------------------------- | -------------- | ------------------------------------------------------------------ |
| `hotelName`               | string         | Partial hotel name (contains, case-insensitive)                    |
| `city`                    | string         | City name (exact match, case-insensitive)                          |
| `country`                 | string         | Country (exact match, case-insensitive)                            |
| `partnerHotelId`          | string         | Your internal hotel ID (exact match)                               |
| `matchedReferenceHotelId` | string         | Reference database hotel ID (exact match)                          |
| `supplierIds`             | array of UUIDs | Limit results to hotels that have external IDs for these suppliers |
| `page`                    | integer        | Page number, 0-indexed (default: `0`)                              |
| `size`                    | integer        | Results per page (default: `20`)                                   |

<Steps>
  <Step title="Run a search">
    Send a POST request with your desired filters. This example finds all hotels named "Hilton" in Paris that have Expedia or Booking.com external IDs:

    ```bash theme={null} theme={null}
    curl -X POST \
      https://api.mapping.travel/api/v1/mapping/f9e8d7c6-b5a4-3210-fedc-ba9876543210/results/search \
      -H "Authorization: Bearer <your-token>" \
      -H "Content-Type: application/json" \
      -d '{
        "hotelName": "Hilton",
        "city": "Paris",
        "supplierIds": [
          "11111111-aaaa-bbbb-cccc-dddddddddddd",
          "22222222-aaaa-bbbb-cccc-dddddddddddd"
        ],
        "page": 0,
        "size": 20
      }'
    ```
  </Step>

  <Step title="Read the response">
    The response wraps results in a paginated envelope:

    ```json theme={null} theme={null}
    {
      "results": [
        {
          "id": "99887766-5544-3322-1100-aabbccddeeff",
          "partnerHotelId": "hotel-001",
          "partnerHotelName": "Hilton Paris Downtown",
          "partnerHotelAddress": "123 Rue de Rivoli",
          "partnerHotelCity": "Paris",
          "partnerHotelCountry": "France",
          "matchedReferenceHotelId": "ref-456",
          "matchedReferenceHotelName": "Hilton Paris Opera",
          "matchConfidence": 95.50,
          "matchMethod": "standard",
          "supplierExternalIds": {
            "11111111-aaaa-bbbb-cccc-dddddddddddd": "EXP-789012",
            "22222222-aaaa-bbbb-cccc-dddddddddddd": "BK-345678"
          },
          "createdAt": "2026-04-25T10:07:42Z",
          "updatedAt": "2026-04-25T10:07:42Z"
        }
      ],
      "totalResults": 43,
      "page": 0,
      "size": 20,
      "totalPages": 3
    }
    ```
  </Step>

  <Step title="Paginate through results">
    Use `page` and `size` to walk through large result sets. Pages are 0-indexed.

    ```bash theme={null} theme={null}
    curl -X POST \
      https://api.mapping.travel/api/v1/mapping/f9e8d7c6-b5a4-3210-fedc-ba9876543210/results/search \
      -H "Authorization: Bearer <your-token>" \
      -H "Content-Type: application/json" \
      -d '{
        "page": 1,
        "size": 20
      }'
    ```

    Continue incrementing `page` until `page >= totalPages - 1`.
  </Step>
</Steps>

## Understanding match fields

### `matchMethod`

The `matchMethod` field tells you how a hotel was matched:

| Value        | Meaning                                                           |
| ------------ | ----------------------------------------------------------------- |
| `"standard"` | Matched by the fuzzy pipeline (STANDARD or HYBRID fallback phase) |
| `"id_to_id"` | Matched by supplier ID (ID\_TO\_ID or HYBRID first phase)         |
| `null`       | No match found                                                    |

Hotels with `matchMethod: null` have a null `matchedReferenceHotelId` and `matchedReferenceHotelName`.

### `matchConfidence`

A decimal score from 0 to 100 representing how confident the fuzzy pipeline is in the match. A score of 100 means an exact match. ID\_TO\_ID matches do not produce a confidence score.

### `supplierExternalIds`

A map of supplier UUID to that supplier's external hotel ID. Only suppliers with a known external ID for the matched reference hotel are included. If you filtered by `supplierIds` in the request, the response only contains results where at least one of those supplier IDs has an entry in this map.

```json theme={null} theme={null}
"supplierExternalIds": {
  "11111111-aaaa-bbbb-cccc-dddddddddddd": "EXP-789012",
  "22222222-aaaa-bbbb-cccc-dddddddddddd": "BK-345678"
}
```

Use these IDs to cross-reference the matched hotel in your own supplier systems.

## Filter reference

<Tabs>
  <Tab title="By hotel name">
    `hotelName` is a partial, case-insensitive search. It matches any hotel whose name contains the string.

    ```json theme={null} theme={null}
    { "hotelName": "grand" }
    ```

    This returns results like "The Grand Budapest", "Grand Hyatt", and "Le Grand Hotel".
  </Tab>

  <Tab title="By location">
    `city` and `country` are exact matches (case-insensitive). Combine them to narrow results to a specific city.

    ```json theme={null} theme={null}
    { "city": "Rome", "country": "Italy" }
    ```
  </Tab>

  <Tab title="By partner ID">
    `partnerHotelId` is an exact match against your own internal hotel identifier.

    ```json theme={null} theme={null}
    { "partnerHotelId": "hotel-001" }
    ```
  </Tab>

  <Tab title="By reference hotel">
    `matchedReferenceHotelId` is an exact match against the reference database hotel ID. Use this to find all your partner hotels that mapped to the same reference hotel.

    ```json theme={null} theme={null}
    { "matchedReferenceHotelId": "ref-456" }
    ```
  </Tab>

  <Tab title="By supplier">
    `supplierIds` filters to results that have external IDs for at least one of the listed suppliers. Supply an array of supplier UUIDs.

    ```json theme={null} theme={null}
    {
      "supplierIds": [
        "11111111-aaaa-bbbb-cccc-dddddddddddd"
      ]
    }
    ```

    Unmatched hotels (no `matchedReferenceHotelId`) are always excluded when filtering by supplier, since they have no supplier external IDs.
  </Tab>
</Tabs>

## Error responses

| HTTP status        | Cause                                                                            |
| ------------------ | -------------------------------------------------------------------------------- |
| `400 Bad Request`  | Negative `page` or `size` value                                                  |
| `401 Unauthorized` | Missing or invalid token, or the mapping job belongs to a different organization |
| `404 Not Found`    | Mapping job ID does not exist                                                    |