> ## 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.
# Mapping Jobs: Matching Your Inventory to Reference Hotels
> A mapping job matches your inventory against the reference dataset. Understand STANDARD, ID_TO_ID, and HYBRID modes, job statuses, and result fields.
A mapping job is an asynchronous process that matches each hotel in your partner inventory against the global reference hotel dataset. You start a job by submitting a `partnerInventoryId` and choosing a mapping mode. The API returns a `mappingJobId` immediately, and you poll for status until the job completes. When it does, you get match counts for every hotel in your file along with a confidence score and a `matchMethod` indicating how each hotel was matched.
## Mapping modes
Mapping.Travel supports three modes. Choose the one that fits your data and how precisely you need to match.
Fuzzy matching using hotel name, address, and location. Works for any inventory, regardless of supplier.
Exact match using supplier hotel IDs. Requires a `supplierCode` on each inventory record and a connected supplier on your account.
Tries ID-to-ID first, then falls back to fuzzy matching for any hotels that did not match. Requires `supplierCode` and a connected supplier.
### STANDARD
STANDARD uses fuzzy matching — it compares hotel names, addresses, and geographic coordinates to find the best match in the reference dataset. Use this mode when:
* You do not have supplier hotel IDs in your inventory
* Your inventory comes from multiple suppliers or an internal system
* You want a single consistent pipeline regardless of supplier
STANDARD works with any inventory. The `supplierCode` field is ignored if present.
### ID\_TO\_ID
ID\_TO\_ID matches each hotel by looking up the supplier's own hotel ID directly in the reference dataset. This is faster and more precise than fuzzy matching. Use this mode when:
* Your inventory contains accurate supplier IDs (e.g., Expedia property IDs)
* You have connected the corresponding supplier on your account
* Match precision is more important than coverage
ID\_TO\_ID requires every record in your inventory to have a `supplierCode` and requires you to have connected the matching supplier. If either condition is not met, the job returns a `400` error before starting.
### HYBRID
HYBRID runs ID-to-ID matching first. Any hotels that do not match via supplier ID are then sent through the fuzzy pipeline. The final result set combines both sets of matches. Use this mode when:
* You have supplier IDs for most but not all of your inventory
* You want maximum coverage without sacrificing precision on the hotels you do have IDs for
Like ID\_TO\_ID, HYBRID requires `supplierCode` on inventory records and a connected supplier. If all hotels match in the ID-to-ID phase, the fuzzy phase is skipped automatically.
## Choosing a mode
Use **ID\_TO\_ID** for the fastest, most precise matches. Make sure your supplier is connected before starting the job.
Use **HYBRID**. Hotels with matching IDs are resolved precisely; the rest fall back to fuzzy matching so you still get results for your full inventory.
Use **STANDARD**. No supplier connection is needed. Matching uses hotel name, address, and location.
## Starting a mapping job
```bash theme={null} theme={null}
curl -X POST https://api.mapping.travel/api/v1/mapping \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"partnerInventoryId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"mode": "HYBRID"
}'
```
If you omit `mode`, the API uses your organization's default mapping mode preference.
## Job status lifecycle
After you start a job, poll `GET /api/v1/mapping/{mappingJobId}` to track progress:
The job has been accepted and is waiting to run.
The matching pipeline is actively processing your inventory.
Matching is finished. Results are available to search and export.
If processing fails, the job moves to `FAILED`. Check the status response for details.
## Reading results
When a job reaches `COMPLETED`, the status response includes aggregate counts:
| Field | Description |
| ---------------- | ------------------------------------------------ |
| `rowCount` | Total number of hotels in your inventory |
| `matchedCount` | Hotels successfully matched to a reference hotel |
| `unmatchedCount` | Hotels with no match found |
To inspect individual hotel-level results, use `POST /api/v1/mapping/{mappingJobId}/results/search`. Each result record includes:
### matchMethod
The `matchMethod` field tells you how a hotel was matched:
| Value | Meaning |
| ------------ | -------------------------------------------------- |
| `"id_to_id"` | Matched via supplier hotel ID |
| `"standard"` | Matched via fuzzy name/address/location comparison |
| `null` | Not matched |
### matchConfidence
`matchConfidence` is a score from `0` to `100` representing the quality of a fuzzy match. Higher scores indicate closer matches. For ID-to-ID matches, confidence is always `100`. For unmatched hotels, this field is `null`.
## Searching results
Use `POST /api/v1/mapping/{mappingJobId}/results/search` to filter results by hotel name, city, country, partner ID, matched reference ID, or supplier IDs.
```bash theme={null} theme={null}
curl -X POST https://api.mapping.travel/api/v1/mapping/3fa85f64-5717-4562-b3fc-2c963f66afa6/results/search \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"city": "Rome",
"page": 0,
"size": 20
}'
```