> ## 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.
# Quickstart: Map Your First Hotel Inventory
> Go from zero to mapped hotel inventory in five steps. Upload a file, start a mapping job, and retrieve matched results against the global reference dataset.
This guide walks you through the core Mapping.Travel API workflow: authenticate, upload an inventory file, start a mapping job, poll for completion, and retrieve your matched results. By the end you will have a working end-to-end integration you can adapt to your own data pipeline.
## Prerequisites
* A Mapping.Travel account with an API token (see [Authentication](/authentication))
* `curl` or any HTTP client
* A hotel inventory file in CSV, JSON, Excel (.xlsx), or Parquet format
Retrieve your API token from **Settings → API tokens** in the Mapping.Travel dashboard. You will use it in every request below.
Set it as an environment variable so you do not have to repeat it:
```bash theme={null} theme={null}
export MT_TOKEN=""
```
Your inventory file must include hotel records with enough information for matching. For CSV, use the following columns:
| Column | Required | Description |
| ----------- | -------- | ---------------------------------- |
| `id` | Yes | Your internal hotel identifier |
| `name` | Yes | Hotel name |
| `address` | No | Street address |
| `city` | Yes | City name |
| `country` | Yes | ISO country code (e.g. `US`, `FR`) |
| `latitude` | No | Decimal latitude |
| `longitude` | No | Decimal longitude |
Example CSV:
```csv theme={null} theme={null}
id,name,address,city,country,latitude,longitude
hotel-001,The Grand Plaza,45 Main Street,New York,US,40.7128,-74.0060
hotel-002,Hotel Metropole,12 Rue de Rivoli,Paris,FR,48.8566,2.3522
hotel-003,Seaside Resort,8 Ocean Drive,Miami,US,25.7617,-80.1918
```
JSON, Excel (.xlsx), and Parquet files are also accepted. The column names must match the schema above regardless of format.
POST your file to `/api/v1/inventory`. The API accepts `multipart/form-data`.
```bash theme={null} theme={null}
curl -X POST https://api.mapping.travel/api/v1/inventory \
-H "Authorization: Bearer $MT_TOKEN" \
-F "file=@hotels.csv"
```
If you are mapping against a specific supplier's ID space (for `ID_TO_ID` or `HYBRID` mode), include the `supplierCode` parameter:
```bash theme={null} theme={null}
curl -X POST https://api.mapping.travel/api/v1/inventory \
-H "Authorization: Bearer $MT_TOKEN" \
-F "file=@hotels.csv" \
-F "supplierCode=expedia"
```
A successful upload returns `201 Created` with an `uploadId`:
```json theme={null} theme={null}
{
"uploadId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"filename": "hotels.csv",
"status": "PROCESSING",
"recordCount": null,
"createdAt": "2026-04-25T10:00:00Z"
}
```
Save the `uploadId`—you need it in the next steps.
Uploads are idempotent. If you upload the same file twice, the API returns the same `uploadId`.
POST to `/api/v1/mapping` with the `partnerInventoryId` from your upload. Choose a `mode` that matches your use case:
* `STANDARD` — fuzzy matching by name and location (recommended for most cases)
* `ID_TO_ID` — match by supplier hotel ID (requires a `supplierCode` on the upload)
* `HYBRID` — try ID-based match first, fall back to fuzzy
```bash theme={null} theme={null}
curl -X POST https://api.mapping.travel/api/v1/mapping \
-H "Authorization: Bearer $MT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"partnerInventoryId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"mode": "STANDARD"
}'
```
A successful response returns `201 Created` with a `mappingJobId`:
```json theme={null} theme={null}
{
"mappingJobId": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
"status": "PENDING",
"mode": "STANDARD",
"createdAt": "2026-04-25T10:01:00Z"
}
```
If your free plan quota is exhausted, you receive a `403` response. Upgrade your plan or wait for the quota to reset.
Mapping jobs run asynchronously. Poll `GET /api/v1/mapping/{mappingJobId}` until `status` is `COMPLETED` or `FAILED`.
```bash theme={null} theme={null}
curl https://api.mapping.travel/api/v1/mapping/f9e8d7c6-b5a4-3210-fedc-ba9876543210 \
-H "Authorization: Bearer $MT_TOKEN"
```
While running:
```json theme={null} theme={null}
{
"mappingJobId": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
"status": "RUNNING",
"mode": "STANDARD",
"totalRecords": 3,
"processedRecords": 1,
"createdAt": "2026-04-25T10:01:00Z",
"updatedAt": "2026-04-25T10:01:15Z"
}
```
When complete:
```json theme={null} theme={null}
{
"mappingJobId": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
"status": "COMPLETED",
"mode": "STANDARD",
"totalRecords": 3,
"processedRecords": 3,
"matchedRecords": 2,
"createdAt": "2026-04-25T10:01:00Z",
"completedAt": "2026-04-25T10:01:45Z"
}
```
Poll every 5–10 seconds for small files. For large inventories, start with a 30-second interval and adjust based on your typical job duration.
Once the job is `COMPLETED`, search the results by POSTing to `/api/v1/mapping/{mappingJobId}/results/search`. You can filter by hotel name, city, country, partner ID, or matched reference ID.
```bash theme={null} theme={null}
curl -X POST https://api.mapping.travel/api/v1/mapping/f9e8d7c6-b5a4-3210-fedc-ba9876543210/results/search \
-H "Authorization: Bearer $MT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"page": 0,
"size": 20
}'
```
The response includes each partner hotel alongside its matched reference hotel:
```json theme={null} theme={null}
{
"totalResults": 2,
"page": 0,
"size": 20,
"totalPages": 1,
"results": [
{
"id": "99887766-5544-3322-1100-aabbccddeeff",
"partnerHotelId": "hotel-001",
"partnerHotelName": "The Grand Plaza",
"partnerHotelCity": "New York",
"partnerHotelCountry": "US",
"matchedReferenceHotelId": "ref-00042",
"matchedReferenceHotelName": "Grand Plaza Hotel New York",
"matchConfidence": 94.0,
"matchMethod": "standard",
"supplierExternalIds": {}
},
{
"id": "aabbccdd-1122-3344-5566-778899001122",
"partnerHotelId": "hotel-002",
"partnerHotelName": "Hotel Metropole",
"partnerHotelCity": "Paris",
"partnerHotelCountry": "FR",
"matchedReferenceHotelId": "ref-01187",
"matchedReferenceHotelName": "Metropole Hotel Paris",
"matchConfidence": 91.0,
"matchMethod": "standard",
"supplierExternalIds": {}
}
]
}
```
Hotels with no match are included with `matchedReferenceHotelId: null` and `matchMethod: null`.
## Next steps
Manage uploads, list past inventories, and download files.
Learn when to use STANDARD, ID\_TO\_ID, and HYBRID modes.
Monitor quota usage and manage your subscription.
Full reference for all endpoints, parameters, and response shapes.