Search Results

After a mapping job reaches COMPLETED status, you can search the individual hotel match results. Filter by hotel name, location, your 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)
`supplierExternalIds`	array of objects	Limit results to hotels matching specific supplier external IDs. Each item is `{ "supplierId": "<supplier-uuid>", "externalId": "<id>" }`
`page`	integer	Page number, 0-indexed (default: `0`)
`size`	integer	Results per page (default: `20`)

Only the fields listed above are accepted. Any unknown field in the request body is rejected with 400 Bad Request, so watch for typos in filter names.

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:

curl -X POST \
  https://api.mapping.travel/api/v1/mapping/f9e8d7c6-b5a4-3210-fedc-ba9876543210/results/search \
  -H "X-API-Key: <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "hotelName": "Hilton",
    "city": "Paris",
    "supplierExternalIds": [
      { "supplierId": "11111111-aaaa-bbbb-cccc-dddddddddddd", "externalId": "EXP-789012" },
      { "supplierId": "22222222-aaaa-bbbb-cccc-dddddddddddd", "externalId": "BK-345678" }
    ],
    "page": 0,
    "size": 20
  }'

Read the response

The response wraps results in a paginated envelope:

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

Paginate through results

Use page and size to walk through large result sets. Pages are 0-indexed.

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

Continue incrementing page until page >= totalPages - 1.

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 supplierExternalIds in the request, the response only contains results whose matched reference hotel has the requested external IDs.

"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

By hotel name
By location
By partner ID
By reference hotel
By supplier

hotelName is a partial, case-insensitive search. It matches any hotel whose name contains the string.

{ "hotelName": "grand" }

This returns results like “The Grand Budapest”, “Grand Hyatt”, and “Le Grand Hotel”.

city and country are exact matches (case-insensitive). Combine them to narrow results to a specific city.

{ "city": "Rome", "country": "Italy" }

partnerHotelId is an exact match against your own internal hotel identifier.

{ "partnerHotelId": "hotel-001" }

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.

{ "matchedReferenceHotelId": "ref-456" }

supplierExternalIds filters to results whose matched reference hotel has the given external ID for the given supplier. Supply an array of { supplierId, externalId } objects.

{
  "supplierExternalIds": [
    { "supplierId": "11111111-aaaa-bbbb-cccc-dddddddddddd", "externalId": "EXP-789012" }
  ]
}

Unmatched hotels (no matchedReferenceHotelId) are always excluded when filtering by supplier, since they have no supplier external IDs.

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

Get Started

Core Concepts

Guides

Delivery destinations

MCP

Agents

Search endpoint

Request fields

Understanding match fields

`matchMethod`

`matchConfidence`

`supplierExternalIds`

Filter reference

Error responses

​Search endpoint

​Request fields

​Understanding match fields

​matchMethod

​matchConfidence

​supplierExternalIds

​Filter reference

​Error responses

Search endpoint

Request fields

Understanding match fields

`matchMethod`

`matchConfidence`

`supplierExternalIds`

Filter reference

Error responses