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

# Run a Hotel Mapping Job

> Start a hotel mapping job against the Mapping.Travel reference database, choose the right mapping mode, and poll for results including match counts.

Once your inventory upload reaches `COMPLETED` status, you can start a mapping job. Mapping.Travel matches your partner hotels against the reference hotel database and returns a count of matched and unmatched hotels. The job runs asynchronously — you poll for its status until it completes.

## Choosing a mapping mode

The `mode` field in your mapping request controls the matching strategy. Choose based on what data you have available.

| Mode       | When to use                                                                          | Requires supplier code |
| ---------- | ------------------------------------------------------------------------------------ | ---------------------- |
| `STANDARD` | You don't have supplier hotel IDs, or you want broad fuzzy matching coverage         | No                     |
| `ID_TO_ID` | You have supplier hotel IDs and want precise, exact-match results                    | Yes                    |
| `HYBRID`   | You want ID\_TO\_ID precision with fuzzy matching as a fallback for unmatched hotels | Yes                    |

**STANDARD** runs a fuzzy matching pipeline against the full reference database. It's the best default choice when you don't have supplier IDs.

**ID\_TO\_ID** matches exclusively by supplier external IDs. Every hotel in your inventory must have a `supplierCode` column, and you must pass the matching `supplierCode` when uploading the file. Hotels without a supplier ID are left unmatched.

**HYBRID** runs ID\_TO\_ID first. Any hotels not matched by ID fall through to the fuzzy pipeline. This gives you the precision of ID matching where possible, with coverage from fuzzy matching for the rest.

<Note>
  `ID_TO_ID` and `HYBRID` both require a `supplierCode` on your inventory upload. If the inventory has no supplier code, the API returns a `400 Bad Request`.
</Note>

<Steps>
  <Step title="Start the mapping job">
    Send a POST request to `/api/v1/mapping` with your `partnerInventoryId` and chosen `mode`.

    <CodeGroup>
      ```bash STANDARD theme={null} theme={null}
      curl -X POST https://api.mapping.travel/api/v1/mapping \
        -H "Authorization: Bearer <your-token>" \
        -H "Content-Type: application/json" \
        -d '{
          "partnerInventoryId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "mode": "STANDARD"
        }'
      ```

      ```bash ID_TO_ID theme={null} theme={null}
      curl -X POST https://api.mapping.travel/api/v1/mapping \
        -H "Authorization: Bearer <your-token>" \
        -H "Content-Type: application/json" \
        -d '{
          "partnerInventoryId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "mode": "ID_TO_ID"
        }'
      ```

      ```bash HYBRID theme={null} theme={null}
      curl -X POST https://api.mapping.travel/api/v1/mapping \
        -H "Authorization: Bearer <your-token>" \
        -H "Content-Type: application/json" \
        -d '{
          "partnerInventoryId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "mode": "HYBRID"
        }'
      ```
    </CodeGroup>

    A successful request returns HTTP 201:

    ```json theme={null} theme={null}
    {
      "mappingJobId": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
      "status": "PENDING",
      "mode": "STANDARD",
      "partnerInventoryId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "createdAt": "2026-04-25T10:05:00Z"
    }
    ```

    Save the `mappingJobId` to poll for status and to search results later.
  </Step>

  <Step title="Poll for job status">
    Check the job status with `GET /api/v1/mapping/{mappingJobId}` until `status` is `COMPLETED` or `FAILED`.

    ```bash theme={null} theme={null}
    curl https://api.mapping.travel/api/v1/mapping/f9e8d7c6-b5a4-3210-fedc-ba9876543210 \
      -H "Authorization: Bearer <your-token>"
    ```

    ```json theme={null} theme={null}
    {
      "mappingJobId": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
      "status": "COMPLETED",
      "mode": "STANDARD",
      "partnerInventoryId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "rowCount": 1000,
      "matchedCount": 923,
      "unmatchedCount": 77,
      "createdAt": "2026-04-25T10:05:00Z",
      "completedAt": "2026-04-25T10:07:42Z"
    }
    ```

    | Status       | Meaning                              |
    | ------------ | ------------------------------------ |
    | `PENDING`    | Queued, not yet started              |
    | `PROCESSING` | Mapping pipeline is running          |
    | `COMPLETED`  | All phases finished successfully     |
    | `FAILED`     | Job failed — check the error message |

    <Tip>
      Poll every 5–10 seconds. Small inventories (under 1,000 hotels) typically complete in under a minute. Larger files may take several minutes.
    </Tip>
  </Step>

  <Step title="Review the results summary">
    The completed job response includes three key counts:

    * **`rowCount`** — total number of hotels in your inventory
    * **`matchedCount`** — hotels successfully matched to a reference hotel
    * **`unmatchedCount`** — hotels with no match found

    For HYBRID jobs, `matchedCount` includes hotels matched by both ID\_TO\_ID and the fuzzy fallback pipeline.

    To see individual match results and drill into specific hotels, use the [search results endpoint](/guides/search-results).
  </Step>
</Steps>

## Quota and credits

Each mapping job counts against your daily quota. On the free plan, you can run 10 mapping jobs per day. On subscription plans, you get a higher daily limit.

If you exceed your daily limit, you need credits to continue. Each credit covers one additional mapping job. The API returns a `403 Forbidden` if you have no remaining quota and no credits.

Check your current quota before starting a job:

```bash theme={null} theme={null}
curl https://api.mapping.travel/api/v1/billing/quota/status \
  -H "Authorization: Bearer <your-token>"
```

See [Billing and Quotas](/guides/billing-and-quotas) for details on purchasing credits and upgrading your plan.

## List all mapping jobs

To view all mapping jobs for your organization:

```bash theme={null} theme={null}
curl "https://api.mapping.travel/api/v1/mapping?page=0&size=20" \
  -H "Authorization: Bearer <your-token>"
```