POST
https://spideriq.ai
/
api
/
v1
/
fuzziq
/
canonical
Add Canonical Record
curl --request POST \
  --url https://spideriq.ai/api/v1/fuzziq/canonical \
  --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>",
  "source": "<string>"
}
'

​
Overview

Manually add a record to your canonical database. This is useful for:
  • Seeding your database with existing customer data
  • Adding records from external sources
  • Pre-populating known duplicates
If the record already exists (based on hash), it will be updated instead of creating a duplicate.

​
Request Body

​
record
object
required
The record to add to canonical database
​
record_type
string
required
Type of record. One of: business, contact, email, profile
​
source
string
default:"manual"
Source identifier (e.g., manual, crm_import, salesforce)

​
Examples

​
Add a Business Record

curl -X POST https://spideriq.ai/api/v1/fuzziq/canonical \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <client_id>:<api_key>:<api_secret>" \
  -d '{
    "record": {
      "company_name": "Acme Corporation",
      "google_place_id": "ChIJabcdefghijk",
      "phone": "+1-555-123-4567",
      "city": "San Francisco",
      "country": "United States"
    },
    "record_type": "business",
    "source": "existing_customer"
  }'

​
Add a Contact Record

curl -X POST https://spideriq.ai/api/v1/fuzziq/canonical \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <client_id>:<api_key>:<api_secret>" \
  -d '{
    "record": {
      "email": "john.doe@acme.com",
      "full_name": "John Doe",
      "linkedin_url": "https://linkedin.com/in/johndoe",
      "position": "VP of Sales",
      "company_name": "Acme Corporation",
      "company_domain": "acme.com"
    },
    "record_type": "contact",
    "source": "crm_export"
  }'

​
Seed from CRM Export

import requests
import csv

headers = {"Authorization": "Bearer <your_token>", "Content-Type": "application/json"}
url = "https://spideriq.ai/api/v1/fuzziq/canonical"

# Import existing customers to prevent re-scraping them
with open("crm_export.csv") as f:
    reader = csv.DictReader(f)
    for row in reader:
        data = {
            "record": {
                "email": row["email"],
                "full_name": row["name"],
                "company_name": row["company"],
                "company_domain": row["website"].replace("https://", "").replace("http://", "")
            },
            "record_type": "contact",
            "source": "crm_salesforce"
        }

        response = requests.post(url, headers=headers, json=data)
        result = response.json()

        if result["was_duplicate"]:
            print(f"Already exists: {row['email']}")
        else:
            print(f"Added: {row['email']}")

​
Response

​
New Record Added

{
  "success": true,
  "canonical_id": 12345,
  "record_hash": "a1b2c3d4e5f6789...",
  "was_duplicate": false
}

​
Duplicate Record (Already Exists)

{
  "success": true,
  "canonical_id": 12345,
  "record_hash": "a1b2c3d4e5f6789...",
  "was_duplicate": true
}

​
Response Fields

FieldTypeDescription
successbooleanWhether the request succeeded
canonical_idintegerID of the canonical record (new or existing)
record_hashstringSHA256 hash of the normalized record
was_duplicatebooleantrue if record already existed

​
Error Responses

​
SpiderFuzzer Not Configured

{
  "detail": "FuzzIQ is not configured"
}
Status Code: 503 Service Unavailable

​
Use Cases

​
1. Seed Existing Customers

Before running campaigns, add your existing customers so they’re automatically deduplicated: 
# Add all existing customers
for customer in existing_customers:
    requests.post(url, json={
        "record": {"company_domain": customer.domain},
        "record_type": "business",
        "source": "existing_customer"
    })

# Now when you run SpiderMaps campaigns, existing customers
# will be marked as duplicates automatically

​
2. Block Specific Records

Add records you want to exclude from future results: 
# Block competitors from appearing in results
competitors = ["competitor1.com", "competitor2.com", "competitor3.com"]

for domain in competitors:
    requests.post(url, json={
        "record": {"company_domain": domain},
        "record_type": "business",
        "source": "blocked_competitor"
    })
For bulk imports (more than a few records), use the Bulk Import endpoint which handles up to 1000 records per request.