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

# Partner Inventory: Hotel Data You Upload for Matching

> A partner inventory is a hotel file you upload for matching. Learn the supported formats, required fields, upload idempotency, and file status lifecycle.

A partner inventory is a file containing your hotel records that you upload to Mapping.Travel for matching against the global reference dataset. Each record represents one hotel in your system, identified by your internal ID and enriched with the name, address, and geographic coordinates needed to find a match. Once uploaded, you reference the inventory by its `uploadId` when starting a mapping job.

## Supported file formats

You can upload inventory files in any of the following formats:

| Format  | Extension  |
| ------- | ---------- |
| CSV     | `.csv`     |
| JSON    | `.json`    |
| Excel   | `.xlsx`    |
| Parquet | `.parquet` |

<Note>
  The maximum file size is **500 MB**. Files larger than this are rejected with a `413` response.
</Note>

## Required and optional fields

Every record in your inventory file must include the following fields:

| Field       | Type   | Description                    |
| ----------- | ------ | ------------------------------ |
| `id`        | string | Your internal hotel identifier |
| `name`      | string | Hotel name                     |
| `address`   | string | Street address                 |
| `city`      | string | City                           |
| `country`   | string | Country (name or ISO code)     |
| `latitude`  | number | Geographic latitude            |
| `longitude` | number | Geographic longitude           |

The following field is optional but required if you want to use ID-to-ID or Hybrid mapping:

| Field          | Type   | Description                                                 |
| -------------- | ------ | ----------------------------------------------------------- |
| `supplierCode` | string | The supplier's own hotel ID (e.g., the Expedia property ID) |

<Tip>
  Include `supplierCode` in your inventory when you have supplier hotel IDs available. This unlocks [ID-to-ID and Hybrid mapping modes](/concepts/mapping), which produce more precise matches than fuzzy matching alone.
</Tip>

## Sample CSV

```csv theme={null} theme={null}
id,name,address,city,country,latitude,longitude,supplierCode
hotel-001,Grand Hotel Roma,Via Veneto 125,Rome,Italy,41.9028,12.4964,6781234
hotel-002,Park Hyatt Milan,Via Tommaso Grossi 1,Milan,Italy,45.4654,9.1866,
hotel-003,Hotel Arts Barcelona,Carrer de la Marina 19-21,Barcelona,Spain,41.3851,2.1734,9023456
```

## Upload idempotency

Uploading the same file twice returns the same `uploadId`. Mapping.Travel identifies duplicate files by their content hash — if the hash matches a file you have already uploaded, the API returns the existing upload record rather than creating a new one. This means you can safely retry failed upload requests without creating duplicate inventories.

## Upload status lifecycle

After you upload a file, you can poll `GET /api/v1/inventory/{uploadId}` to track its progress. An upload moves through the following statuses:

<Steps>
  <Step title="PENDING">
    The file has been received and is queued for processing.
  </Step>

  <Step title="PROCESSING">
    The file is being parsed and validated.
  </Step>

  <Step title="COMPLETED">
    The file has been processed successfully. The inventory is ready to use in a mapping job.
  </Step>
</Steps>

If something goes wrong, the upload moves to one of these terminal states:

| Status      | Meaning                                                                         |
| ----------- | ------------------------------------------------------------------------------- |
| `FAILED`    | Processing encountered an error. Check the response for details.                |
| `CANCELLED` | You cancelled the upload by calling `POST /api/v1/inventory/{uploadId}/cancel`. |

<Warning>
  You can only cancel an upload while it is in `PENDING` or `PROCESSING` status. Once an upload reaches `COMPLETED` or `FAILED`, it cannot be cancelled.
</Warning>

## Managing your inventories

Use the following endpoints to work with your inventory files:

| Endpoint                                    | Description                                               |
| ------------------------------------------- | --------------------------------------------------------- |
| `POST /api/v1/inventory`                    | Upload a new inventory file                               |
| `GET /api/v1/inventory`                     | List all inventories for your organization                |
| `GET /api/v1/inventory/{uploadId}`          | Get the status of a specific upload                       |
| `GET /api/v1/inventory/{uploadId}/download` | Generate a signed download URL (expires after 60 seconds) |
| `POST /api/v1/inventory/{uploadId}/cancel`  | Cancel an in-progress upload                              |