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

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

1. PENDING

   The file has been received and is queued for processing.

2. PROCESSING

   The file is being parsed and validated.

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