POST
https://spideriq.ai
/
api
/
v1
/
fuzziq
/
check
Check Single Record
curl --request POST \
  --url https://spideriq.ai/api/v1/fuzziq/check \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "record": {
    "email": "<string>",
    "full_name": "<string>",
    "first_name": "<string>",
    "last_name": "<string>",
    "linkedin_url": "<string>",
    "position": "<string>",
    "company_name": "<string>",
    "company_domain": "<string>",
    "google_place_id": "<string>",
    "website": "<string>",
    "phone": "<string>",
    "city": "<string>",
    "country": "<string>"
  },
  "record_type": "<string>",
  "add_to_canonical": true,
  "campaign_id": "<string>",
  "threshold": 123
}
'

​
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

​
record
object
required
The record to check for duplicates
​
record_type
string
required
Type of record. One of: business, contact, email, profile
​
add_to_canonical
boolean
default:"true"
If true and record is unique, automatically add to canonical database
​
campaign_id
string
Campaign ID for scoped deduplication. When provided, deduplication is scoped to records from this campaign only.
​
threshold
number
default:"0.5"
Confidence threshold for ML matching (0.0-1.0). Currently only exact matching is active.

​
Examples

​
Check a Business Record

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
  }'

​
Check a Contact Record

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

FieldTypeDescription
successbooleanWhether the request succeeded
is_duplicatebooleantrue if record matches an existing canonical record
confidencenumberMatch confidence (0.0-1.0). Always 1.0 for exact matches
matched_record_idintegerID of matched canonical record (if duplicate)
match_typestringType of match: exact_hash, email, google_place_id, linkedin_url, phone, company_domain
canonical_idintegerID of new canonical record (if unique and add_to_canonical=true)
added_to_canonicalbooleanWhether record was added to canonical database
skippedbooleanWhether deduplication was skipped
reasonstringReason if skipped (e.g., fuzziq_not_configured)

​
Record Types

TypeBest ForKey Fields
businessGoogle Maps resultsgoogle_place_id, company_name, phone
contactPeople/contactsemail, full_name, linkedin_url
emailEmail-only recordsemail
profileLinkedIn profileslinkedin_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
Each client has an isolated PostgreSQL schema for their canonical records. Your data is never mixed with other clients.