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

# 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

```bash theme={null} theme={null}
POST https://api.mapping.travel/api/v1/mapping
```

<ParamField body="partnerInventoryId" type="string" required>
  UUID of the partner inventory to map. The inventory must already be uploaded and belong to your organization.
</ParamField>

<ParamField body="mode" type="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. |
</ParamField>

<Warning>
  `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.
</Warning>

## Response

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

<ResponseField name="mappingJobId" type="string" required>
  UUID of the newly created mapping job. Use this to poll for status and access results.
</ResponseField>

<ResponseField name="partnerInventoryId" type="string" required>
  UUID of the partner inventory being mapped.
</ResponseField>

<ResponseField name="status" type="string" required>
  Initial status of the job. Always `PENDING` immediately after creation.
</ResponseField>

<ResponseField name="mode" type="string" required>
  The resolved mapping mode used for this job — either the mode you specified or your organization's configured default.
</ResponseField>

<ResponseField name="createdAt" type="string" required>
  ISO 8601 timestamp of when the job was created.
</ResponseField>

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

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

## Example

<RequestExample>
  ```bash cURL theme={null} theme={null}
  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"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null} theme={null}
  {
    "mappingJobId": "f7e6d5c4-b3a2-1098-fedc-ba9876543210",
    "partnerInventoryId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "PENDING",
    "mode": "HYBRID",
    "createdAt": "2026-04-25T09:00:00Z"
  }
  ```

  ```json 400 theme={null} theme={null}
  {
    "error": "Bad Request",
    "message": "HYBRID mode requires a supplierCode on the inventory"
  }
  ```

  ```json 403 theme={null} theme={null}
  {
    "error": "Forbidden",
    "message": "Daily mapping quota exceeded. Upgrade to Paid plan for unlimited mappings."
  }
  ```

  ```json 404 theme={null} theme={null}
  {
    "error": "Not Found",
    "message": "Partner inventory not found"
  }
  ```
</ResponseExample>