> ## 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 mapping results for a job

> Filter and paginate individual hotel match results from a completed mapping job by name, city, partner ID, reference ID, or supplier.

Use this endpoint to explore the hotel-level results of a completed mapping job. You can filter by hotel name, city, country, partner hotel ID, matched reference hotel ID, and supplier IDs. Each result includes the match confidence score, match method, and a map of external IDs from connected suppliers for the matched reference hotel.

<Note>
  All filters are optional and combinable. Omit any filter to return results regardless of that field's value. Results are scoped to a single mapping job — cross-job search is not supported.
</Note>

## Request

```bash theme={null} theme={null}
POST https://api.mapping.travel/api/v1/mapping/{mappingJobId}/results/search
```

<ParamField path="mappingJobId" type="string" required>
  UUID of the mapping job whose results you want to search.
</ParamField>

<ParamField body="hotelName" type="string">
  Filters results where the partner hotel name contains this string. The match is case-insensitive.
</ParamField>

<ParamField body="city" type="string">
  Filters results to hotels in this city. Exact match, case-insensitive.
</ParamField>

<ParamField body="country" type="string">
  Filters results to hotels in this country. Exact match, case-insensitive.
</ParamField>

<ParamField body="partnerHotelId" type="string">
  Filters to a specific partner hotel by its ID. Exact match.
</ParamField>

<ParamField body="matchedReferenceHotelId" type="string">
  Filters to results matched to a specific reference hotel ID. Exact match.
</ParamField>

<ParamField body="supplierIds" type="string[]">
  List of supplier UUIDs. When provided, only results where the matched reference hotel has an external ID for at least one of the specified suppliers are returned. Unmatched hotels are excluded when this filter is active.
</ParamField>

<ParamField body="page" type="number" default="0">
  Page number to retrieve. 0-indexed.
</ParamField>

<ParamField body="size" type="number" default="20">
  Number of results per page.
</ParamField>

## Response

<ResponseField name="results" type="object[]" required>
  Array of matching hotel result records for the current page.

  <Expandable title="result properties">
    <ResponseField name="id" type="string" required>
      UUID of the mapping result record.
    </ResponseField>

    <ResponseField name="partnerHotelId" type="string">
      The partner's own ID for this hotel, as provided in the uploaded inventory.
    </ResponseField>

    <ResponseField name="partnerHotelName" type="string">
      Name of the hotel from the partner inventory.
    </ResponseField>

    <ResponseField name="partnerHotelAddress" type="string">
      Street address from the partner inventory.
    </ResponseField>

    <ResponseField name="partnerHotelCity" type="string">
      City from the partner inventory.
    </ResponseField>

    <ResponseField name="partnerHotelCountry" type="string">
      Country from the partner inventory.
    </ResponseField>

    <ResponseField name="matchedReferenceHotelId" type="string">
      ID of the reference hotel this partner hotel was matched to. `null` if the hotel was not matched.
    </ResponseField>

    <ResponseField name="matchedReferenceHotelName" type="string">
      Name of the matched reference hotel. `null` if unmatched.
    </ResponseField>

    <ResponseField name="matchConfidence" type="number">
      Confidence score for the match, from `0` to `100`. Higher values indicate a stronger match. `null` if the hotel was not matched.
    </ResponseField>

    <ResponseField name="matchMethod" type="string">
      How this hotel was matched.

      | Value      | Description                                         |
      | ---------- | --------------------------------------------------- |
      | `id_to_id` | Matched by exact supplier ID in the ID-to-ID phase. |
      | `standard` | Matched by fuzzy name/address comparison.           |
      | `null`     | Hotel was not matched.                              |
    </ResponseField>

    <ResponseField name="supplierExternalIds" type="object" required>
      Map of supplier UUID to the external ID that supplier uses for the matched reference hotel. Only populated for matched hotels. Empty object `{}` for unmatched hotels or when no supplier IDs are configured.

      ```json theme={null} theme={null}
      {
        "uuid-of-expedia": "EXP-789",
        "uuid-of-booking": "BK-101112"
      }
      ```
    </ResponseField>

    <ResponseField name="createdAt" type="string" required>
      ISO 8601 timestamp of when this result record was created.
    </ResponseField>

    <ResponseField name="updatedAt" type="string" required>
      ISO 8601 timestamp of the last update to this result record.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="totalResults" type="number" required>
  Total number of results matching the applied filters, across all pages.
</ResponseField>

<ResponseField name="page" type="number" required>
  The current page number (0-indexed).
</ResponseField>

<ResponseField name="size" type="number" required>
  The number of results per page as requested.
</ResponseField>

<ResponseField name="totalPages" type="number" required>
  Total number of pages for the current result set.
</ResponseField>

## Error responses

| Status             | Reason                                                                                             |
| ------------------ | -------------------------------------------------------------------------------------------------- |
| `400 Bad Request`  | Invalid pagination parameters (e.g., negative `page` or `size`).                                   |
| `401 Unauthorized` | Missing or invalid `Authorization` header, or the mapping job belongs to a different organization. |
| `404 Not Found`    | No mapping job with the given ID exists for your organization.                                     |

<Warning>
  If you provide `supplierIds` that do not exist in the system, no error is returned. Those supplier IDs are silently skipped during enrichment, and results that only have external IDs for unknown suppliers will be excluded.
</Warning>

## Example

<RequestExample>
  ```bash cURL theme={null} theme={null}
  curl --request POST \
    --url https://api.mapping.travel/api/v1/mapping/f7e6d5c4-b3a2-1098-fedc-ba9876543210/results/search \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "hotelName": "Hilton",
      "city": "Paris",
      "supplierIds": [
        "11111111-2222-3333-4444-555555555555",
        "66666666-7777-8888-9999-000000000000"
      ],
      "page": 0,
      "size": 20
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null} theme={null}
  {
    "results": [
      {
        "id": "aaaabbbb-cccc-dddd-eeee-ffff00001111",
        "partnerHotelId": "partner-123",
        "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-2222-3333-4444-555555555555": "EXP-789",
          "66666666-7777-8888-9999-000000000000": "BK-101112"
        },
        "createdAt": "2026-04-25T09:08:45Z",
        "updatedAt": "2026-04-25T09:08:45Z"
      }
    ],
    "totalResults": 150,
    "page": 0,
    "size": 20,
    "totalPages": 8
  }
  ```

  ```json 400 theme={null} theme={null}
  {
    "error": "Bad Request",
    "message": "Page size must be greater than 0"
  }
  ```

  ```json 404 theme={null} theme={null}
  {
    "error": "Not Found",
    "message": "Mapping job not found"
  }
  ```
</ResponseExample>