GET
https://spideriq.ai
/
api
/
v1
/
fuzziq
/
canonical
List Canonical Records
curl --request GET \
  --url https://spideriq.ai/api/v1/fuzziq/canonical \
  --header 'Authorization: Bearer <token>'

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_type
string
Filter by record type. One of: business, contact, email, profile
campaign_id
string
Filter by campaign ID to see records from a specific campaign
limit
integer
default:"100"
Maximum records to return (1-1000)
offset
integer
default:"0"
Offset for pagination

Examples

List All Records

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

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

FieldTypeDescription
successbooleanWhether the request succeeded
recordsarrayArray of canonical records
totalintegerTotal records matching filter (for pagination)
limitintegerLimit used in this request
offsetintegerOffset used in this request

Record Object

FieldTypeDescription
idintegerUnique canonical record ID
record_hashstringSHA256 hash of normalized record
record_typestringType: business, contact, email, profile
emailstringEmail address (if present)
full_namestringFull name (if present)
company_namestringCompany/business name (if present)
company_domainstringCompany domain (if present)
google_place_idstringGoogle Place ID (if present)
linkedin_urlstringLinkedIn URL (if present)
phonestringPhone number (if present)
citystringCity (if present)
countrystringCountry (if present)
source_workerstringWorker that created record
campaign_idstringCampaign ID (if from campaign)
created_atstringISO 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
Use the Stats endpoint to get a count without fetching all records.