ExisEcho API

Integrate powerful fuzzy matching into your applications

Quick Start

Base URL: https://api.fuzzy-logic.com

All requests require an API key in the X-API-Key header. Get your API key

Endpoints

POST /api/match

Find duplicates within a single dataset. Compares all records against each other.

POST /api/compare

Compare two datasets to find matches between them. Does not compare records within the same dataset.

GET /api/health

Health check endpoint. No authentication required.

Authentication

Include your API key in the request header:

X-API-Key: your-api-key-here

Usage & Billing

API usage is measured in units. Each unit represents 2 records processed.

Each response includes your remaining units in the usage field.

POST /api/match

Find duplicates within a single dataset.

Request Body

{
  "records": [
    { "id": "1", "fields": { "name": "John Smith", "email": "john@example.com" } },
    { "id": "2", "fields": { "name": "Jon Smyth", "email": "jon@example.com" } },
    { "id": "3", "fields": { "name": "Jane Doe", "email": "jane@example.com" } }
  ],
  "matchingColumns": ["name"],
  "threshold": 0.7,
  "maxResults": 100,
  "columnOptions": {
    "name": {
      "weight": 2.0,
      "usePhoneticMatching": true,
      "equateSynonyms": true,
      "ignoreCase": true,
      "ignoreWordOrder": true
    }
  }
}

Response

{
  "success": true,
  "matches": [
    {
      "record1Id": "1",
      "record2Id": "2",
      "score": 0.89,
      "quality": "Very High"
    }
  ],
  "summary": {
    "totalRecordsAnalyzed": 3,
    "totalMatches": 1,
    "averageScore": 0.89,
    "maxScore": 0.89,
    "minScore": 0.89,
    "processingTimeMs": 12,
    "thresholdUsed": 0.7
  },
  "usage": {
    "unitsConsumed": 2,
    "unitsRemaining": 9998
  }
}

POST /api/compare

Compare two datasets to find matches between them.

Request Body

{
  "sourceRecords": [
    { "id": "s1", "fields": { "company": "Acme Corporation", "city": "New York" } },
    { "id": "s2", "fields": { "company": "Beta Industries", "city": "Boston" } }
  ],
  "targetRecords": [
    { "id": "t1", "fields": { "company": "ACME Corp", "city": "NYC" } },
    { "id": "t2", "fields": { "company": "Gamma LLC", "city": "Chicago" } }
  ],
  "matchingColumns": ["company"],
  "threshold": 0.7,
  "columnOptions": {
    "company": {
      "removePunctuation": true,
      "equateSynonyms": true
    }
  }
}

Column Options Reference

Option Type Default Description
weight number 1.0 Importance multiplier (0.1 to 10.0)
usePhoneticMatching boolean false Match words that sound alike (Smith/Smyth)
equateSynonyms boolean false Treat synonyms as equal (Bob=Robert, Corp=Corporation)
removeHonorifics boolean false Remove titles (Mr., Mrs., Dr., etc.)
removePunctuation boolean true Strip punctuation and special characters
removeArticles boolean false Remove articles (a, an, the)
removeAllBlanks boolean false Remove all whitespace
removeDigits boolean false Remove numeric digits
removeNonDigits boolean false Keep only digits (for phone numbers, IDs)
ignoreCase boolean true Case-insensitive comparison
ignoreWordOrder boolean false Match regardless of word order
matchingCharacters integer 0 Match first N chars only (0=all)
removeCustomWords array null List of words to remove before matching

Code Examples

Python

# pip install requests
import requests

API_KEY = "your-api-key"
BASE_URL = "https://api.fuzzy-logic.com"

# Find duplicates within a dataset
def find_duplicates(records, threshold=0.7):
    response = requests.post(
        f"{BASE_URL}/api/match",
        headers={"X-API-Key": API_KEY},
        json={
            "records": records,
            "threshold": threshold,
            "columnOptions": {
                "name": {
                    "usePhoneticMatching": True,
                    "equateSynonyms": True,
                    "ignoreWordOrder": True
                }
            }
        }
    )
    return response.json()

# Example usage
records = [
    {"id": "1", "fields": {"name": "John Smith", "city": "New York"}},
    {"id": "2", "fields": {"name": "Jon Smyth", "city": "NYC"}},
    {"id": "3", "fields": {"name": "Jane Doe", "city": "Boston"}}
]

result = find_duplicates(records)

if result["success"]:
    print(f"Found {result['summary']['totalMatches']} potential duplicates")
    for match in result["matches"]:
        print(f"  {match['record1Id']} <-> {match['record2Id']}: {match['score']:.0%} ({match['quality']})")
    print(f"Units remaining: {result['usage']['unitsRemaining']}")
else:
    print(f"Error: {result['error']}")

JavaScript / Node.js

const API_KEY = "your-api-key";
const BASE_URL = "https://api.fuzzy-logic.com";

// Find duplicates within a dataset
async function findDuplicates(records, threshold = 0.7) {
  const response = await fetch(`${BASE_URL}/api/match`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": API_KEY
    },
    body: JSON.stringify({
      records,
      threshold,
      columnOptions: {
        name: {
          usePhoneticMatching: true,
          equateSynonyms: true,
          ignoreWordOrder: true
        }
      }
    })
  });
  return response.json();
}

// Compare two datasets
async function compareDatasets(sourceRecords, targetRecords, threshold = 0.7) {
  const response = await fetch(`${BASE_URL}/api/compare`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": API_KEY
    },
    body: JSON.stringify({
      sourceRecords,
      targetRecords,
      threshold,
      matchingColumns: ["name", "email"]
    })
  });
  return response.json();
}

// Example usage
const records = [
  { id: "1", fields: { name: "John Smith", city: "New York" } },
  { id: "2", fields: { name: "Jon Smyth", city: "NYC" } },
  { id: "3", fields: { name: "Jane Doe", city: "Boston" } }
];

findDuplicates(records).then(result => {
  if (result.success) {
    console.log(`Found ${result.summary.totalMatches} potential duplicates`);
    result.matches.forEach(match => {
      console.log(`  ${match.record1Id} <-> ${match.record2Id}: ${(match.score * 100).toFixed(0)}%`);
    });
  } else {
    console.error(`Error: ${result.error}`);
  }
});

Error Codes

HTTP Status Error Code Description
400 too_many_records Request exceeds 10,000 record limit
401 missing_api_key X-API-Key header not provided
401 invalid_api_key API key not found or invalid
401 expired API key has expired
402 quota_exhausted No units remaining. Purchase more.
429 rate_limit_* Rate limit exceeded. Check Retry-After header.

Ready to Get Started?

Get your API key and start integrating fuzzy matching into your applications today.

Get API Key Contact Sales