Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mappingtravel.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

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

FieldTypeDescription
hotelNamestringPartial hotel name (contains, case-insensitive)
citystringCity name (exact match, case-insensitive)
countrystringCountry (exact match, case-insensitive)
partnerHotelIdstringYour internal hotel ID (exact match)
matchedReferenceHotelIdstringReference database hotel ID (exact match)
supplierIdsarray of UUIDsLimit results to hotels that have external IDs for these suppliers
pageintegerPage number, 0-indexed (default: 0)
sizeintegerResults per page (default: 20)
1

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

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
}
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 "Authorization: Bearer <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:
ValueMeaning
"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)
nullNo 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. 
"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

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”.

​
Error responses

HTTP statusCause
400 Bad RequestNegative page or size value
401 UnauthorizedMissing or invalid token, or the mapping job belongs to a different organization
404 Not FoundMapping job ID does not exist