---
title: "Submit an async hotel-match batch job"
method: POST
path: "/hotels/match/async"
tags: ["Async Hotel Match"]
---

# Submit an async hotel-match batch job

`POST /hotels/match/async`

## Request

- Base URL: `https://api.liteapi.travel/v3.0`
- URL: `https://api.liteapi.travel/v3.0/hotels/match/async`
- Auth: API key in header `X-API-Key`

## Overview

Upload an onboarding CSV of hotel rows (name, country, optional address/coordinates) and start an async **content-based** hotel matching job. Returns immediately with a `job_id` to poll.

Use this when partner hotel IDs are unavailable and you need to match hotels by content against Nuitee inventory.

## When to Use

- **Bulk onboarding** - Match many hotels by name/location when partner IDs are not available
- **Large files** - Jobs above the inline row limit are processed via chunked workers
- **GCS workflows** - Submit with `input_gcs` / `output_gcs` for large files outside the API body limit

## What You Get

- **202 Accepted** - Initial `JobStatus` with `status: queued` and `job_id`
- **Progress polling** - Use `GET /hotels/match/async/jobs/{jobId}/status` until `status` is `done` or `error`
- **Result CSV** - Download via `GET /hotels/match/async/jobs/{jobId}` when complete

## Quick Start

1. POST `multipart/form-data` with `file` (CSV), or JSON `{ "input_gcs": "gs://..." }` for large files
2. Poll status with the returned `job_id`
3. Download the result CSV when `status` is `done`

Input CSV must include `name` and `country` columns (accepted header aliases vary upstream). Optional `output_gcs` writes the result directly to GCS instead of returning CSV through the API.

Authenticate with your LiteAPI `X-API-Key`.

**Rate limit:** 50 requests/min (production), 10 requests/min (sandbox).

**Platform note:** Multipart uploads are capped at 32 MiB through this API hop — use GCS input mode for larger files.

## Request body

- HotelMatchBatchSubmitJSON
  - `input_gcs` string, required: GCS URI of the input CSV
  - `output_gcs` string: Optional GCS URI for the result CSV

## Response `202`

Job accepted

- JobStatus
  - `job_id` string, uuid, required
  - `status` 'queued' | 'running' | 'done' | 'error', required
  - `total` integer
  - `done` integer
  - `matched` integer
  - `review` integer
  - `no_match` integer
  - `geo_match_name_mismatch` integer
  - `name_match_geo_mismatch` integer
  - `error` string
  - `output_gcs` string
  - `input_gcs` string
  - `created_at` string, date-time
  - `updated_at` string, date-time
  - `total_chunks` integer
  - `chunks_done` integer

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `413`: Payload Too Large
- `429`: Rate limit exceeded
- `502`: Upstream mapping service unreachable
- `504`: Upstream mapping service timed out

---

[API](https://skmtc.dev/liteapi/apis/api-mapping.md) - [All operations](https://skmtc.dev/liteapi/apis/api-mapping/llms.txt) - [OpenAPI document](https://skmtc.dev/liteapi/apis/api-mapping/revisions/82f8d27a93af?raw)