Fuzzy Matching Prompt for Entity Resolution

This prompt is for data engineers and integration developers who need to match a raw input string against a list of canonical entities. The primary job-to-be-done is resolution, not retrieval. You already have a controlled candidate list—such as a product catalog, a customer master, or a set of standard vendor names—and you need to determine which canonical entity a new, possibly messy input string refers to. The prompt handles exact matches, fuzzy matches, abbreviation expansion, and phonetic similarity, returning a scored, explainable match decision that can route to automated ingestion or a human review queue.

The ideal user has a pre-existing canonical list and needs a deterministic, auditable matching layer before data hits a system of record. Required context includes the raw input string, the full candidate list (or a pre-filtered subset), a similarity threshold, and any domain-specific abbreviation or synonym mappings. This prompt is not a search prompt. Do not use it when the candidate list is unknown, when you need to retrieve candidates from a large vector database, or when the matching logic requires deep semantic understanding of product descriptions or long-form text. For those cases, a retrieval-augmented generation (RAG) or embedding-based similarity approach is more appropriate.

Before wiring this into a production pipeline, define your match confidence thresholds and decide which match types can be auto-accepted versus which require human review. Exact matches and high-confidence fuzzy matches above your threshold can flow directly to downstream systems. Cases with multiple high-score candidates, low-confidence matches, or phonetic-only matches should be flagged for a review queue. Always log the match type, score, and candidate list version for auditability. Avoid using this prompt for real-time, user-facing search where latency and candidate list size would make the approach impractical.

This prompt template is designed to be pasted directly into your system instructions for an LLM-based entity resolution service. It accepts an input string, a candidate list of canonical entities, and a similarity threshold, then returns the best match with a score, match type classification, and explicit handling of ambiguous cases. The template uses square-bracket placeholders that you must replace with your specific data before each API call. The output is structured JSON suitable for direct ingestion into a master data management (MDM) pipeline or a human review queue.

textCopy
You are an entity resolution engine. Your task is to match an input string to a canonical entity from a provided candidate list.

## INPUT
- Input String: [INPUT_STRING]
- Candidate Entities: [CANDIDATE_LIST]
- Similarity Threshold: [SIMILARITY_THRESHOLD]

## MATCHING RULES
1. Calculate a similarity score (0.0 to 1.0) between the input string and each candidate.
2. Consider exact matches, fuzzy string similarity (typos, transpositions), common abbreviations, and phonetic similarity (Soundex/Metaphone).
3. A match is valid only if its score is >= [SIMILARITY_THRESHOLD].
4. If no candidate meets the threshold, return a "no_match" decision.
5. If multiple candidates exceed the threshold and the top two scores are within 0.1 of each other, flag the result for human disambiguation.

## OUTPUT SCHEMA
Return ONLY a valid JSON object with this exact structure:
{
  "decision": "match" | "no_match" | "ambiguous",
  "best_match": {
    "canonical_entity": string | null,
    "score": number | null,
    "match_type": "exact" | "fuzzy" | "abbreviation" | "phonetic" | null
  },
  "candidates_considered": [
    {
      "entity": string,
      "score": number,
      "match_type": string
    }
  ],
  "requires_review": boolean,
  "review_reason": string | null
}

## CONSTRAINTS
- Do not invent canonical entities. Only match against the provided [CANDIDATE_LIST].
- If the input string is empty or nonsensical, return a "no_match" decision with an empty best_match.
- If the candidate list is empty, return a "no_match" decision.

To adapt this template for your environment, replace [INPUT_STRING] with the raw, unnormalized string from your source system. Populate [CANDIDATE_LIST] with an array of your canonical entity names, sourced from your golden record database. Set [SIMILARITY_THRESHOLD] to a float between 0.0 and 1.0; start with 0.8 for high-precision use cases like financial counterparty matching, or lower to 0.6 for noisier data like user-entered product names. Before deploying, validate the output JSON against the schema in your application code. For high-risk domains, always route records where requires_review is true to a human operator and log the full candidates_considered payload for auditability. Do not use this prompt for matching personally identifiable information (PII) without appropriate data handling and redaction controls in your pipeline.

The fuzzy matching prompt is a single step in a larger entity resolution workflow. In production, you will typically call this prompt inside a loop that iterates over unresolved input strings, each paired with a candidate list retrieved from your canonical entity store. The prompt itself should be treated as a stateless function: it receives one input string, one candidate list, and one similarity threshold, and it returns a structured match decision. Do not batch multiple inputs into a single prompt call unless you have validated that your model reliably maintains output structure across variable-length batches. Instead, fan out calls per input and aggregate results in application code.

Before calling the model, apply a pre-filter in application code to reduce the candidate list size and control token costs. Use a fast, deterministic method such as trigram similarity, Soundex, or a vector similarity search against pre-computed embeddings of your canonical entity names. Pass only the top-K candidates (typically 5–15) to the prompt. This keeps the prompt context small, reduces latency, and prevents the model from wasting tokens on obviously irrelevant candidates. Log the pre-filter method, the K value, and the candidate IDs passed to the prompt for each call so you can debug false negatives later.

After receiving the model response, validate the output against a strict schema before trusting it. At minimum, confirm that best_match is either a candidate ID from the provided list or an explicit null, that score is a float between 0.0 and 1.0, that match_type is one of the allowed enum values (exact, fuzzy, abbreviation, phonetic), and that multiple_candidates is a list of objects with id and score fields. If validation fails, retry once with the same input and an added instruction to strictly follow the output schema. If the retry also fails, route the input to a human review queue with the raw model response attached for diagnosis.

For high-stakes entity resolution—such as customer identity merging, financial counterparty mapping, or healthcare provider matching—never auto-commit a match decision above a configurable confidence threshold without human approval. Set a auto_accept_threshold (e.g., 0.95) in your application config. Matches with scores above this threshold and match_type of exact can be auto-resolved. Matches with scores between a review_threshold (e.g., 0.70) and the auto-accept threshold, or any match where multiple_candidates contains a second candidate within a tie_margin (e.g., 0.05) of the top score, should be queued for human disambiguation. Matches below the review threshold should be treated as no-match and either create a new canonical entity or remain unresolved, depending on your domain rules.

Choose your model based on the complexity of the name variants you encounter. For straightforward exact and near-exact matching with minor punctuation differences, a fast, cost-effective model like GPT-4o-mini or Claude Haiku is sufficient. If your data contains heavy abbreviations, phonetic variations, or multilingual name forms, use a more capable model like GPT-4o or Claude Sonnet. Always run a calibration set of 50–100 known match pairs and non-match pairs through your chosen model before deploying, and measure precision and recall at your chosen thresholds. Log every prompt call with input, candidates, model response, validation result, and final action (auto-resolved, queued for review, or rejected) for auditability and threshold tuning over time.