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

# Recipe: Propose matches for unmatched rows

> Auto-surface candidate matches for any unmatched mapping result so a human can approve in seconds.

When a mapping job finishes, some rows always come back unmatched. This recipe configures an agent to search the golden dataset for each one and file the top N candidates as pending items for a human reviewer.

## What you'll build

An agent that, on every `MappingJobFinishedEvent`:

1. Pulls the job's unmatched results.
2. Calls `search_golden_dataset` (by name) and `search_golden_dataset_by_geo` (by coordinates) per row.
3. Files a `MATCH_PROPOSAL` pending item with the top 3 candidates.

A human then opens **Pending**, picks a candidate (or rejects all), and the link is made.

## Prerequisites

* Pro Max workspace.
* At least one historical mapping job with unmatched rows.

## Steps

<Steps>
  <Step title="Create the agent">
    **Agents → New Agent.** Pick the starter template *"Triage unmatched rows"*. It pre-fills the goal and rules.
  </Step>

  <Step title="Goal">
    > Watch every mapping job. For each unmatched row, search the golden dataset by name and by geo, and propose the top 3 candidates as pending items.
  </Step>

  <Step title="Scope">
    Optional — narrow to a specific supplier (e.g. `BOOKING`) if you only want this for one source.
  </Step>

  <Step title="Rules">
    ```json theme={null}
    {
      "mapping_jobs": { "trigger_on_new_inventory_upload": true },
      "unmatched_results": {
        "propose_candidates_for_review": true,
        "max_candidates_per_row": 3,
        "search_strategies": ["geo", "name"]
      }
    }
    ```
  </Step>

  <Step title="Activate">
    Click **Activate**. The next mapping job that finishes will trigger the agent.
  </Step>
</Steps>

## Equivalent API call

```bash theme={null}
curl -X POST https://api.mapping.travel/api/v1/agents \
  -H 'Authorization: Bearer mt_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Unmatched-row triage",
    "goal": "Watch every mapping job. For each unmatched row, search the golden dataset by name and by geo, and propose the top 3 candidates as pending items.",
    "scope": { "suppliers": ["BOOKING"] },
    "dailySpendCapCents": 500,
    "hourlyActionCap": 60
  }'
```

Then `POST /agents/{id}/rule-sets` with the JSON above and `POST /agents/{id}/activate`.

## Reviewing pending items

<img src="https://mintlify.s3.us-west-1.amazonaws.com/mappingtravel/images/agents/pending-tab.png" alt="Pending tab with match proposals" />

Each `MATCH_PROPOSAL` item shows:

* The unmatched partner row (name + address).
* 3 candidate reference hotels with `referenceHotelId`, name, distance, and the agent's 1-sentence reasoning.
* **Accept** (links the result) / **Reject** (dismisses) buttons.

## Related

* [Agents overview](/agents/overview) — broader context.
* [Rules and decisions](/agents/rules-and-decisions) — full rule schema.
* [Triage mismatches to pending](/agents/recipes/triage-mismatches-to-pending) — the sibling recipe for mismatches.