Add Canonical Record

POST/api/v1/fuzziq/canonical

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

recordobjectrequired

The record to add to canonical database

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

sourcestringdefault: manual

Source identifier (e.g., manual, crm_import, salesforce)

Examples

Add a Business Record

cURL

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

Python

import requests

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

data = {
    "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"
}

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

result = response.json()
print(f"Added with ID: {result['canonical_id']}")

JavaScript

const response = await fetch(
  'https://spideriq.ai/api/v1/fuzziq/canonical',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer <your_token>',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      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"
    })
  }
);

const data = await response.json();
console.log(`Added with ID: ${data.canonical_id}`);

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

Field	Type	Description
success	boolean	Whether the request succeeded
canonical_id	integer	ID of the canonical record (new or existing)
record_hash	string	SHA256 hash of the normalized record
was_duplicate	boolean	true 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"
    })

note

For bulk imports (more than a few records), use the Bulk Import endpoint which handles up to 1000 records per request.