Fuzzy-match a value against a list
Heuristicmatching_best_matchBest-effort — fuzzy, approximate, or inferred; check the confidence score.
Find the best fuzzy matches for a query string in a list of candidates. Returns ranked matches with scores. Useful for entity resolution: 'which known entity does this input refer to?' Supports limit, score_cutoff, and strategy parameters. Tip: for organization or facility names, run names_org_name_clean on the query and candidates first so casing and punctuation don't depress scores (raw fuzzy matching, not semantic — heavy abbreviations may still miss). Processing multiple inputs? Use `matching_best_match_batch` to do up to 100 in one call.
Parameters
querystringrequiredThe string to find matches for.
candidatesarrayrequiredList of candidate strings to match against.
strategystringoptionalSimilarity strategy: ratio (character-level), partial_ratio (best substring), token_sort_ratio (ignores word order), token_set_ratio (ignores order + duplicates, default).
limitintegeroptionalMax results to return.
score_cutoffnumberoptionalMinimum score threshold (0.0–1.0).
Call it
curl -X POST https://api.snipget.ai/v1/matching/best-match \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{"query":"Jon Smith","candidates":["John Smith","Jonathan Smithe","Jane Doe","J. Smith"],"strategy":"token_set_ratio","limit":5,"score_cutoff":0.5}'The Batch tab sends up to 1000 inputs in one call via /v1/matching/best-match/batch.
Example response
{
"query": "Jon Smith",
"matches": [
{
"value": "John Smith",
"score": 0.9474,
"index": 0
},
{
"value": "J. Smith",
"score": 0.8235,
"index": 3
},
{
"value": "Jonathan Smithe",
"score": 0.75,
"index": 1
}
],
"match_count": 3,
"strategy": "token_set_ratio"
}FAQ
What problem does this solve?
You have one messy value and a known list (customers, products, locations), and you want to know which entries it most likely refers to. It scores the query against every candidate and returns the top matches ranked best-first, which is the core of 'entity resolution.'
Are the matches guaranteed to be correct?
No. This is a heuristic, best-effort ranking by text similarity, not an authoritative lookup. Each match carries a score from 0 to 1; the top result is your best candidate, but you should read the score and confirm before treating it as a true match.
How do I control how many results I get back?
Use limit to cap how many matches are returned (default 5) and score_cutoff to drop weak matches below a similarity threshold (default 0.50). Raise the cutoff to be stricter; candidates scoring below it are left out entirely, and you can get zero matches.
What does the index in each match mean?
It is the position of that match in the candidate list you sent (starting at 0), so you can map a result straight back to the original row or record it came from.
What if my query is blank or the candidate list is empty?
A blank query gets a normal response with no matches, match_count 0, and confidence 0 plus a reason in the trace — not an error, so check match_count. An empty candidate list gets that same no-match response over MCP, while the REST endpoint requires at least one candidate and rejects the request instead.