Upload Inventory

Before you can run a mapping job, 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:

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:

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

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

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.

curl -X POST https://api.mapping.travel/api/v1/inventory \
  -H "X-API-Key: <your-token>" \
  -F "file=@hotels.csv"

curl -X POST "https://api.mapping.travel/api/v1/inventory?supplierCode=expedia" \
  -H "X-API-Key: <your-token>" \
  -F "file=@hotels.csv"

A successful upload returns HTTP 202 Accepted with an upload object:

{
  "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.

Poll for processing status

The API processes your file asynchronously. Poll GET /api/v1/inventory/{uploadId} until status is COMPLETED.

curl https://api.mapping.travel/api/v1/inventory/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-API-Key: <your-token>"

{
  "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

Poll every 2 to 5 seconds. Most files complete within 30 seconds, but large Parquet files may take a few minutes.

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

If status is FAILED, do not use that uploadId to start a mapping job. Fix the issue and re-upload.

List your inventories

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

curl "https://api.mapping.travel/api/v1/inventory?page=0&size=20" \
  -H "X-API-Key: <your-token>"

Cancel an in-progress upload

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

curl -X POST https://api.mapping.travel/api/v1/inventory/a1b2c3d4-e5f6-7890-abcd-ef1234567890/cancel \
  -H "X-API-Key: <your-token>"

Get Started

Core Concepts

Guides

Delivery destinations

MCP

Agents

File format

List your inventories

Cancel an in-progress upload

​File format

​List your inventories

​Cancel an in-progress upload

File format

List your inventories

Cancel an in-progress upload