Score a pair before reviewing a duplicate

Your import has “Acme Inc” in one record and “Acme Incorporated” in another. Should someone review them as a possible duplicate?

match-score gives you a 0–100 similarity score for two field values, plus their normalized forms. Each comparison costs $0.003 USDC, paid over x402 on Base mainnet.

Keep the scope precise. One call compares one pair of strings. For an agent checking company records, that means sending the company-name fields while keeping the source record IDs in its own workflow.

The result gives your review queue a concrete admission rule. You choose the threshold.

Send the field values and their type

Submit a JSON body to the endpoint: 

POST https://x402.agentutility.ai/match-score
Content-Type: application/json

{
  "a": "Acme Inc",
  "b": "Acme Incorporated",
  "type": "company"
}

This shows the application request body. Use your x402-capable client to handle payment and submit the paid request.

a is the first value you want to compare. It's required and must be a nonempty string after surrounding whitespace is trimmed. Send the field's text directly.

b is the second value. The same requirements apply. Each string can contain up to 500 characters after trimming; longer inputs receive HTTP 413. Missing or blank values receive HTTP 400.

type tells the endpoint what kind of values you're comparing. The accepted strings are: 

["company", "name", "address", "email", "phone", "text"]

It's optional and defaults to text. An unrecognized value also falls back to text, so agents should validate this field before sending it. Use company explicitly for company names.

And keep record identifiers outside the payload. There's no input field for a record ID or a review threshold.

Read the response as evidence

The company-name example produces: 

{
  "a": "Acme Inc",
  "b": "Acme Incorporated",
  "type": "company",
  "score": 100,
  "same_key": true,
  "normalized_a": "acme",
  "normalized_b": "acme"
}

The response echoes the trimmed inputs and the selected type. score is a number; same_key is a boolean.

Here, both values normalize to acme. They share a match key, which produces a score of 100. That gives a reviewer a reason to inspect the underlying records. Company names alone don't establish that two records describe the same business.

What happens with “Acme Supply”? Comparing it against “Acme Inc” with the same type produces this response: 

{
  "a": "Acme Inc",
  "b": "Acme Supply",
  "type": "company",
  "score": 72,
  "same_key": false,
  "normalized_a": "acme",
  "normalized_b": "acme supply"
}

Now the reviewer can see the extra word behind the comparison. Preserve both normalized values beside the original fields so the queue shows what was compared.

Set a review threshold in your workflow

Suppose you're testing a review threshold of 70. Both example pairs enter the queue, with the 100-point pair sorted first. At 80, only the first pair enters.

Those are example policies. A score of 72 isn't a 72% probability that the records are duplicates.

Your routing code can make the choice explicit: 

const reviewThreshold = 70;
const comparison = await response.json();

const reviewItem = {
  leftRecordId: "crm-1042",
  rightRecordId: "import-887",
  comparison,
  needsReview: comparison.score >= reviewThreshold
};

The record IDs here are illustrative, and response is the successful paid HTTP response. The threshold lives in your application.

Start with pairs that a reviewer has already labeled. Check which known duplicates fall below your proposed cutoff, then inspect how many unrelated pairs enter the queue. Choose thresholds separately for the field types you're using.

But keep acceptance separate from queue admission. A high-scoring company-name pair still needs whatever evidence your merge policy requires, such as a matching business address.

For larger imports, narrow candidate pairs before paying for comparisons. At $0.003 per call, 1,000 comparisons cost $3 USDC. Save each result with its source record IDs so a reviewer can open the exact pair that triggered the threshold.