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

1. Create the agent

   Agents → New Agent. Pick the starter template “Triage unmatched rows”. It pre-fills the goal and rules.

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

3. Scope

   Optional — narrow to a specific supplier (e.g. BOOKING) if you only want this for one source.

4. Rules

   {
     "mapping_jobs": { "trigger_on_new_inventory_upload": true },
     "unmatched_results": {
       "propose_candidates_for_review": true,
       "max_candidates_per_row": 3,
       "search_strategies": ["geo", "name"]
     }
   }
   
5. Activate

   Click Activate. The next mapping job that finishes will trigger the agent.

Equivalent API call

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

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 — broader context.
• Rules and decisions — full rule schema.
• Triage mismatches to pending — the sibling recipe for mismatches.