Start Mapping Job

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

Request

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

string

required

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

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 202 Accepted with a job object. Use the mappingJobId to check status or retrieve results.

string

required

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

string

required

UUID of the partner inventory being mapped.

string

required

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

string

required

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

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 `X-API-Key` 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 --request POST \
  --url https://api.mapping.travel/api/v1/mapping \
  --header 'X-API-Key: <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "partnerInventoryId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "mode": "HYBRID"
  }'

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

{
  "error": "Bad Request",
  "message": "HYBRID mode requires a supplierCode on the inventory"
}

{
  "error": "Forbidden",
  "message": "Daily mapping quota exceeded. Upgrade to Paid plan for unlimited mappings."
}

{
  "error": "Not Found",
  "message": "Partner inventory not found"
}

Inventory

Mapping

Reference Hotels

Suppliers

Webhooks

Export

Request

Response

Error responses

Example

​Request

​Response

​Error responses

​Example

Request

Response

Error responses

Example