Partner Inventory

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, 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`

The maximum file size is 500 MB. Files larger than this are rejected with a 413 response.

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)

Include supplierCode in your inventory when you have supplier hotel IDs available. This unlocks ID-to-ID and Hybrid mapping modes, which produce more precise matches than fuzzy matching alone.

Sample CSV

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

PENDING

The file has been received and is queued for processing.

PROCESSING

The file is being parsed and validated.

COMPLETED

The file has been processed successfully. The inventory is ready to use in a mapping job.

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

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.

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

Get Started

Core Concepts

Guides

Delivery destinations

MCP

Agents

Supported file formats

Required and optional fields

Sample CSV

Upload idempotency

Upload status lifecycle

Managing your inventories

​Supported file formats

​Required and optional fields

​Sample CSV

​Upload idempotency

​Upload status lifecycle

​Managing your inventories

Supported file formats

Required and optional fields

Sample CSV

Upload idempotency

Upload status lifecycle

Managing your inventories