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

# Upload and Prepare Your Hotel Inventory File

> Prepare and upload a hotel inventory file in CSV, JSON, Excel, or Parquet format, then poll for processing status before starting a mapping job.

Before you can run a mapping job, you need to upload your hotel inventory to Mapping.Travel. The API accepts CSV, JSON, Excel (.xlsx), and Parquet files up to 500 MB. Uploading is idempotent — if you upload the same file twice, the API returns the same upload ID rather than creating a duplicate.

## File format

Your inventory file must include the following columns. Column names are case-sensitive.

| Column         | Required | Description                                                                |
| -------------- | -------- | -------------------------------------------------------------------------- |
| `id`           | Yes      | Your internal hotel identifier                                             |
| `name`         | Yes      | Hotel name                                                                 |
| `address`      | No       | Street address                                                             |
| `city`         | Yes      | City                                                                       |
| `country`      | Yes      | Country (full name or ISO code)                                            |
| `latitude`     | No       | Decimal latitude                                                           |
| `longitude`    | No       | Decimal longitude                                                          |
| `supplierCode` | No       | Supplier code for ID\_TO\_ID or HYBRID mapping (e.g. `expedia`, `booking`) |

**Example CSV:**

```csv theme={null} theme={null}
id,name,address,city,country,latitude,longitude
hotel-001,The Grand Budapest,1 Mendl's Square,Zubrowka,PL,51.1079,17.0385
hotel-002,Hotel Chevalier,15 Rue Monseigneur,Paris,FR,48.8566,2.3522
hotel-003,Royal Tenenbaum,111 Archer Avenue,New York,US,40.7128,-74.0060
```

If you plan to use ID\_TO\_ID or HYBRID mapping, include the `supplierCode` query parameter when uploading and add your supplier's hotel IDs in a `supplierCode` column:

```csv theme={null} theme={null}
id,name,address,city,country,latitude,longitude,expedia
hotel-001,The Grand Budapest,1 Mendl's Square,Zubrowka,PL,51.1079,17.0385,12345678
hotel-002,Hotel Chevalier,15 Rue Monseigneur,Paris,FR,48.8566,2.3522,98765432
```

<Steps>
  <Step title="Prepare your file">
    Export your hotel data in one of the supported formats. Make sure every row has at minimum an `id`, `name`, `city`, and `country`. Remove any rows with blank IDs — they will cause the upload to fail with a 400 error.

    If your file is larger than 500 MB, split it into multiple uploads and run a separate mapping job for each.
  </Step>

  <Step title="Upload the file">
    Send a `multipart/form-data` POST request to `/api/v1/inventory`. Include your supplier code as a query parameter if you have one.

    <CodeGroup>
      ```bash Standard upload theme={null} theme={null}
      curl -X POST https://api.mapping.travel/api/v1/inventory \
        -H "Authorization: Bearer <your-token>" \
        -F "file=@hotels.csv"
      ```

      ```bash Upload with supplier code theme={null} theme={null}
      curl -X POST "https://api.mapping.travel/api/v1/inventory?supplierCode=expedia" \
        -H "Authorization: Bearer <your-token>" \
        -F "file=@hotels.csv"
      ```
    </CodeGroup>

    A successful upload returns HTTP 201 with an upload object:

    ```json theme={null} theme={null}
    {
      "uploadId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "status": "PENDING",
      "filename": "hotels.csv",
      "fileSize": 204800,
      "supplierCode": null,
      "createdAt": "2026-04-25T10:00:00Z"
    }
    ```

    Save the `uploadId` — you need it to check status and to start a mapping job.
  </Step>

  <Step title="Poll for processing status">
    The API processes your file asynchronously. Poll `GET /api/v1/inventory/{uploadId}` until `status` is `COMPLETED`.

    ```bash theme={null} theme={null}
    curl https://api.mapping.travel/api/v1/inventory/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
      -H "Authorization: Bearer <your-token>"
    ```

    ```json theme={null} theme={null}
    {
      "uploadId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "status": "COMPLETED",
      "filename": "hotels.csv",
      "fileSize": 204800,
      "supplierCode": null,
      "createdAt": "2026-04-25T10:00:00Z"
    }
    ```

    | Status       | Meaning                                     |
    | ------------ | ------------------------------------------- |
    | `PENDING`    | Queued, not yet started                     |
    | `PROCESSING` | File is being parsed and validated          |
    | `COMPLETED`  | Ready to use in a mapping job               |
    | `FAILED`     | Processing failed — check the error message |
    | `CANCELLED`  | You cancelled the upload                    |

    <Tip>
      Poll every 2–5 seconds. Most files complete within 30 seconds, but large Parquet files may take a few minutes.
    </Tip>
  </Step>

  <Step title="Handle errors">
    If the upload fails, the response will include an error message explaining what went wrong.

    | HTTP status                  | Cause                                                   | Fix                                         |
    | ---------------------------- | ------------------------------------------------------- | ------------------------------------------- |
    | `400 Bad Request`            | Empty file, missing required columns, or malformed data | Check your file format and required columns |
    | `413 Payload Too Large`      | File exceeds 500 MB                                     | Split the file into smaller chunks          |
    | `415 Unsupported Media Type` | File format not supported                               | Convert to CSV, JSON, Excel, or Parquet     |
    | `429 Too Many Requests`      | Upload rate limit exceeded                              | Wait and retry with exponential backoff     |

    <Warning>
      If `status` is `FAILED`, do not use that `uploadId` to start a mapping job. Fix the issue and re-upload.
    </Warning>
  </Step>
</Steps>

## List your inventories

To see all previously uploaded inventories for your organization, use the list endpoint:

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

## Cancel an in-progress upload

If you need to stop an upload that is still `PENDING` or `PROCESSING`, send a cancel request:

```bash theme={null} theme={null}
curl -X POST https://api.mapping.travel/api/v1/inventory/a1b2c3d4-e5f6-7890-abcd-ef1234567890/cancel \
  -H "Authorization: Bearer <your-token>"
```