Start a hotel mapping job

Start an asynchronous job to match partner inventory against the reference hotel database. Specify STANDARD, ID_TO_ID, or HYBRID mode. Returns a mappingJobId.

Use this endpoint to start a new mapping job for a partner inventory. The job runs asynchronously — you receive a job ID immediately and can poll the status endpoint to track progress. Once complete, the results are available via the search endpoint and can be exported on demand.

Request

POST https://api.mapping.travel/api/v1/mapping

partnerInventoryId · string · required

UUID of the partner inventory to map. The inventory must already be uploaded and belong to your organization.

mode · string

Mapping mode to use. If omitted, your organization’s default mode preference is applied.

Value	Description
STANDARD	Fuzzy matching pipeline. Works for any inventory, regardless of supplier codes.
ID_TO_ID	Exact supplier ID matching. Requires a supplierCode on the inventory and a connected supplier.
HYBRID	Runs ID-to-ID matching first, then falls back to fuzzy matching for any hotels that remain unmatched. Requires a supplierCode on the inventory.

ID_TO_ID and HYBRID modes require the inventory to have a supplierCode set and a connected supplier configured in your organization. If either condition is not met, the request returns 400 Bad Request before a job is created.

Response

A successful request returns HTTP 201 Created with a job object. Use the mappingJobId to check status or retrieve results.

mappingJobId · string · required

UUID of the newly created mapping job. Use this to poll for status and access results.

partnerInventoryId · string · required

UUID of the partner inventory being mapped.

status · string · required

Initial status of the job. Always PENDING immediately after creation.

mode · string · required

The resolved mapping mode used for this job — either the mode you specified or your organization’s configured default.

createdAt · string · required

ISO 8601 timestamp of when the job was created.

Error responses

Status	Reason
400 Bad Request	ID_TO_ID or HYBRID mode requested but inventory has no supplierCode, or supplier is not supported.
401 Unauthorized	Missing or invalid Authorization header.
403 Forbidden	Your organization’s mapping quota is exceeded, or you have insufficient credits.
404 Not Found	The specified partnerInventoryId does not exist or does not belong to your organization.

Free plan organizations have a daily mapping limit. Once the limit is reached, additional mappings require available credits. Upgrade to a paid plan for unlimited mappings.

Example

cURL

curl --request POST \
  --url https://api.mapping.travel/api/v1/mapping \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "partnerInventoryId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "mode": "HYBRID"
  }'

201

{
  "mappingJobId": "f7e6d5c4-b3a2-1098-fedc-ba9876543210",
  "partnerInventoryId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "PENDING",
  "mode": "HYBRID",
  "createdAt": "2026-04-25T09:00:00Z"
}