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.

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.

Request

POST https://api.mapping.travel/api/v1/mapping/{mappingJobId}/results/search

mappingJobId · string · required

UUID of the mapping job whose results you want to search.

hotelName · string

Filters results where the partner hotel name contains this string. The match is case-insensitive.

city · string

Filters results to hotels in this city. Exact match, case-insensitive.

country · string

Filters results to hotels in this country. Exact match, case-insensitive.

partnerHotelId · string

Filters to a specific partner hotel by its ID. Exact match.

matchedReferenceHotelId · string

Filters to results matched to a specific reference hotel ID. Exact match.

supplierIds · 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.

page · number · default: "0"

Page number to retrieve. 0-indexed.

size · number · default: "20"

Number of results per page.

Response

results · object[] · required

Array of matching hotel result records for the current page.

Show result properties

id · string · required

UUID of the mapping result record.

partnerHotelId · string

The partner’s own ID for this hotel, as provided in the uploaded inventory.

partnerHotelName · string

Name of the hotel from the partner inventory.

partnerHotelAddress · string

Street address from the partner inventory.

partnerHotelCity · string

City from the partner inventory.

partnerHotelCountry · string

Country from the partner inventory.

matchedReferenceHotelId · string

ID of the reference hotel this partner hotel was matched to. null if the hotel was not matched.

matchedReferenceHotelName · string

Name of the matched reference hotel. null if unmatched.

matchConfidence · number

Confidence score for the match, from 0 to 100. Higher values indicate a stronger match. null if the hotel was not matched.

matchMethod · 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.

supplierExternalIds · 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.

{
  "uuid-of-expedia": "EXP-789",
  "uuid-of-booking": "BK-101112"
}

createdAt · string · required

ISO 8601 timestamp of when this result record was created.

updatedAt · string · required

ISO 8601 timestamp of the last update to this result record.

totalResults · number · required

Total number of results matching the applied filters, across all pages.

page · number · required

The current page number (0-indexed).

size · number · required

The number of results per page as requested.

totalPages · number · required

Total number of pages for the current result set.

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.

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.

Example

cURL

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
  }'

200

{
  "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
}