List Canonical Records

GET/api/v1/fuzziq/canonical

Overview

Retrieve canonical records from your SpiderFuzzer database. Each client has an isolated PostgreSQL schema, so you only see your own records.

Use this endpoint to:

• Browse your canonical database
• Export records for analysis
• Verify specific records were added
• Filter by record type or campaign

Query Parameters

record_typestring

Filter by record type. One of: business, contact, email, profile

campaign_idstring

Filter by campaign ID to see records from a specific campaign

limitintegerdefault: 100

Maximum records to return (1-1000)

offsetintegerdefault: 0

Offset for pagination

Examples

List All Records

cURL

curl -X GET "https://spideriq.ai/api/v1/fuzziq/canonical?limit=50" \
  -H "Authorization: Bearer <client_id>:<api_key>:<api_secret>"

Python

import requests

headers = {"Authorization": "Bearer <your_token>"}

response = requests.get(
    "https://spideriq.ai/api/v1/fuzziq/canonical",
    headers=headers,
    params={"limit": 50}
)

data = response.json()
print(f"Total records: {data['total']}")

for record in data["records"]:
    print(f"- {record['company_name'] or record['email']} ({record['record_type']})")

JavaScript

const response = await fetch(
  'https://spideriq.ai/api/v1/fuzziq/canonical?limit=50',
  {
    headers: {
      'Authorization': 'Bearer <your_token>'
    }
  }
);

const data = await response.json();
console.log(`Total records: ${data.total}`);

Filter by Record Type

# Get only business records
curl -X GET "https://spideriq.ai/api/v1/fuzziq/canonical?record_type=business&limit=100" \
  -H "Authorization: Bearer <client_id>:<api_key>:<api_secret>"

Filter by Campaign

# Get records from a specific campaign
curl -X GET "https://spideriq.ai/api/v1/fuzziq/canonical?campaign_id=camp_restaurants_paris&limit=100" \
  -H "Authorization: Bearer <client_id>:<api_key>:<api_secret>"

Paginate Through All Records

import requests

headers = {"Authorization": "Bearer <your_token>"}
base_url = "https://spideriq.ai/api/v1/fuzziq/canonical"

offset = 0
limit = 100
all_records = []

while True:
    response = requests.get(
        base_url,
        headers=headers,
        params={"limit": limit, "offset": offset}
    )
    data = response.json()

    all_records.extend(data["records"])

    if len(data["records"]) < limit:
        break  # No more records

    offset += limit

print(f"Retrieved {len(all_records)} total records")

Response

{
  "success": true,
  "records": [
    {
      "id": 12345,
      "record_hash": "a1b2c3d4e5f6...",
      "record_type": "business",
      "email": null,
      "full_name": null,
      "company_name": "McDonald's Paris",
      "company_domain": null,
      "google_place_id": "ChIJ123456789",
      "linkedin_url": null,
      "phone": "+33-1-23-45-67-89",
      "city": "Paris",
      "country": "France",
      "source_worker": "spiderMaps",
      "campaign_id": "camp_restaurants_paris",
      "created_at": "2025-01-05T10:30:00Z"
    },
    {
      "id": 12346,
      "record_hash": "b2c3d4e5f6g7...",
      "record_type": "contact",
      "email": "john.doe@example.com",
      "full_name": "John Doe",
      "company_name": "Example Corp",
      "company_domain": "example.com",
      "google_place_id": null,
      "linkedin_url": "https://linkedin.com/in/johndoe",
      "phone": null,
      "city": null,
      "country": null,
      "source_worker": "spiderSite",
      "campaign_id": null,
      "created_at": "2025-01-05T11:00:00Z"
    }
  ],
  "total": 15420,
  "limit": 100,
  "offset": 0
}

Response Fields

Field	Type	Description
success	boolean	Whether the request succeeded
records	array	Array of canonical records
total	integer	Total records matching filter (for pagination)
limit	integer	Limit used in this request
offset	integer	Offset used in this request

Record Object

Field	Type	Description
id	integer	Unique canonical record ID
record_hash	string	SHA256 hash of normalized record
record_type	string	Type: business, contact, email, profile
email	string	Email address (if present)
full_name	string	Full name (if present)
company_name	string	Company/business name (if present)
company_domain	string	Company domain (if present)
google_place_id	string	Google Place ID (if present)
linkedin_url	string	LinkedIn URL (if present)
phone	string	Phone number (if present)
city	string	City (if present)
country	string	Country (if present)
source_worker	string	Worker that created record
campaign_id	string	Campaign ID (if from campaign)
created_at	string	ISO 8601 creation timestamp

Notes

• Records are sorted by created_at descending (newest first)
• Deleted records (soft delete) are not returned
• Maximum 1000 records per request

note

Use the Stats endpoint to get a count without fetching all records.