Check Single Record

POST/api/v1/fuzziq/check

Overview

Check a single record against your canonical database to determine if it's a duplicate. Optionally add unique records to the canonical database automatically.

SpiderFuzzer uses tiered matching:

1. Exact hash - SHA256 hash of normalized record fields
2. Indexed fields - Direct match on email, google_place_id, linkedin_url, phone, or company_domain

Request Body

recordobjectrequired

The record to check for duplicates

Record Fields

emailstring

Email address (max 255 chars)

full_namestring

Full name (max 500 chars)

first_namestring

First name (max 255 chars)

last_namestring

Last name (max 255 chars)

linkedin_urlstring

LinkedIn profile URL (max 500 chars)

positionstring

Job title/position (max 255 chars)

company_namestring

Company/business name (max 500 chars)

company_domainstring

Company website domain (max 255 chars)

google_place_idstring

Google Place ID (max 100 chars)

websitestring

Website URL (max 500 chars)

phonestring

Phone number (max 50 chars)

citystring

City (max 255 chars)

countrystring

Country (max 100 chars)

record_typestringrequired

Type of record. One of: business, contact, email, profile

add_to_canonicalbooleandefault: true

If true and record is unique, automatically add to canonical database

campaign_idstring

Campaign ID for scoped deduplication. When provided, deduplication is scoped to records from this campaign only.

thresholdnumberdefault: 0.5

Confidence threshold for ML matching (0.0-1.0). Currently only exact matching is active.

Examples

Check a Business Record

cURL

curl -X POST https://spideriq.ai/api/v1/fuzziq/check \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <client_id>:<api_key>:<api_secret>" \
  -d '{
    "record": {
      "company_name": "McDonald'\''s Paris",
      "google_place_id": "ChIJ123456789",
      "phone": "+33-1-23-45-67-89",
      "city": "Paris",
      "country": "France"
    },
    "record_type": "business",
    "add_to_canonical": true
  }'

Python

import requests

headers = {
    "Authorization": "Bearer <your_token>",
    "Content-Type": "application/json"
}

data = {
    "record": {
        "company_name": "McDonald's Paris",
        "google_place_id": "ChIJ123456789",
        "phone": "+33-1-23-45-67-89",
        "city": "Paris",
        "country": "France"
    },
    "record_type": "business",
    "add_to_canonical": True
}

response = requests.post(
    "https://spideriq.ai/api/v1/fuzziq/check",
    headers=headers,
    json=data
)

print(response.json())

JavaScript

const response = await fetch(
  'https://spideriq.ai/api/v1/fuzziq/check',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer <your_token>',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      record: {
        company_name: "McDonald's Paris",
        google_place_id: "ChIJ123456789",
        phone: "+33-1-23-45-67-89",
        city: "Paris",
        country: "France"
      },
      record_type: "business",
      add_to_canonical: true
    })
  }
);

const data = await response.json();
console.log(data);

Check a Contact Record

cURL

curl -X POST https://spideriq.ai/api/v1/fuzziq/check \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <client_id>:<api_key>:<api_secret>" \
  -d '{
    "record": {
      "email": "john.doe@example.com",
      "full_name": "John Doe",
      "linkedin_url": "https://linkedin.com/in/johndoe",
      "position": "CEO",
      "company_name": "Example Corp"
    },
    "record_type": "contact",
    "add_to_canonical": true
  }'

Response

Unique Record (New)

{
  "success": true,
  "is_duplicate": false,
  "confidence": 0.0,
  "matched_record_id": null,
  "match_type": null,
  "canonical_id": 12345,
  "added_to_canonical": true,
  "skipped": false,
  "reason": null
}

Duplicate Record (Found Match)

{
  "success": true,
  "is_duplicate": true,
  "confidence": 1.0,
  "matched_record_id": 12345,
  "match_type": "google_place_id",
  "canonical_id": null,
  "added_to_canonical": false,
  "skipped": false,
  "reason": null
}

SpiderFuzzer Not Configured

{
  "success": true,
  "is_duplicate": false,
  "skipped": true,
  "reason": "fuzziq_not_configured"
}

Response Fields

Field	Type	Description
success	boolean	Whether the request succeeded
is_duplicate	boolean	true if record matches an existing canonical record
confidence	number	Match confidence (0.0-1.0). Always 1.0 for exact matches
matched_record_id	integer	ID of matched canonical record (if duplicate)
match_type	string	Type of match: exact_hash, email, google_place_id, linkedin_url, phone, company_domain
canonical_id	integer	ID of new canonical record (if unique and add_to_canonical=true)
added_to_canonical	boolean	Whether record was added to canonical database
skipped	boolean	Whether deduplication was skipped
reason	string	Reason if skipped (e.g., fuzziq_not_configured)

Record Types

Type	Best For	Key Fields
business	Google Maps results	google_place_id, company_name, phone
contact	People/contacts	email, full_name, linkedin_url
email	Email-only records	email
profile	LinkedIn profiles	linkedin_url, full_name

Match Priority

SpiderFuzzer checks fields in this order (first match wins):

1. google_place_id - Exact match (highest priority for businesses)
2. email - Exact match (normalized, lowercase)
3. linkedin_url - Exact match (normalized)
4. phone - Exact match (normalized, digits only)
5. company_domain - Exact match
6. exact_hash - SHA256 hash of all normalized fields

note

Each client has an isolated PostgreSQL schema for their canonical records. Your data is never mixed with other clients.