v4 Pixel Edition

Data Aviator API Reference

The complete reference for the Data Aviator v4 Pixel and REST API. Build audiences, enrich contacts, and resolve anonymous visitors into real people and companies with 50+ data points.

Authentication

All API requests require an X-Api-Key header. Obtain your key from the Data Aviator dashboard at build.data-aviator.com.

Base URL

All endpoints use the base URL:
https://api.data-aviator.com

Pagination

List endpoints support page and page_size parameters. Default page size is 100, maximum is 1000.

Example: Authenticated Request

curl --request GET \
  --url 'https://api.data-aviator.com/audiences?page=1&page_size=100' \
  --header 'X-Api-Key: YOUR_API_KEY'

Important: Authentication Method

The Data Aviator API only accepts the X-Api-Key header for authentication. The Authorization: Bearer header, query parameters (?api_key=), and other auth methods are not supported and will return a "missing API key" error.

Subaccount users: Each subaccount has its own API key. There is no master-key impersonation — each subaccount must generate their own key from their dashboard at build.data-aviator.com.

Data Aviator / V4 Super Pixel

The Limitless Event Ingestion Engine

Stop tracking pageviews. Start tracking your actual business logic. Standard pixels give you a rigid menu of basic events and force your complex customer journey to fit their limited mold. The V4 Super Pixel is different.

Auto-Tracked by Default

16 Events

Page views, clicks, scroll, engagement, performance, tab visibility, exit, SPA navigation, errors, deep scroll, exit intent, idle detection, video, file downloads, form submits, and clipboard — all captured automatically. Zero configuration.

Full Tracking Capability

50+ Event Types

The planned SDK API will unlock the complete taxonomy — e-commerce, B2B SaaS, advertising, fintech, travel, content, and user lifecycle. 16 events fire automatically today.

Schema-Less Architecture

Zero Limits

No hardcoded restrictions. You define the taxonomy — the pixel acts as the courier. If an action happens in your business, the V4 Super Pixel can capture it.

The "Track Anything" Promise

Fuel Hyper-Targeted Ad Spend

Feed specific intent signals into Data Aviator Ads. Retarget users who configured a product but dropped off before launching — not just anyone who visited your site.

Trigger Intelligent Automation

Turn system events into immediate communication. When a user hits a milestone or completes registration, pipe that trigger into Data Aviator Send for a highly contextual welcome series.

Close the Loop on Revenue

Track the complete lifecycle from the first inbound search to the final pipeline conversion — giving sales and marketing a unified source of truth.

Installation

Add a single script tag to the <head> of every page you want tracked. Replace YOUR_PIXEL_ID with the ID returned from POST /pixels.

install.html

<script async
  src="https://cdn.data-aviator.com/v4/pixel.js"
  data-pixel-id="YOUR_PIXEL_ID"></script>

Architecture

Persistent Visitor ID

The pixel mints a stable visitor_id on first contact, stores it in first-party storage, and reuses it on every subsequent visit. Identity survives navigation, tab close, and session boundaries.

Session Management

A new session begins after 30 minutes of inactivity or when the visitor returns from a different referrer. Each session aggregates its events into one resolution context.

Event Batching

The pixel batches events client-side and flushes them to https://api.data-aviator.com/v4/events every 2 seconds, on visibility change, and on page unload via navigator.sendBeacon — no events lost on exit.

Context Collection

Every event is decorated with: page URL, referrer, viewport, screen, language, timezone, user-agent client hints, document depth, scroll position, and elapsed-time-on-page.

v2.1.0 Capabilities

Brave Browser Detection

Fingerprint Brave's privacy modifications and adjust the resolution model accordingly — Brave's stricter cookie behavior is detected and routed through the IP-based resolver.

Incognito / Private Browsing

Detect private mode without breaking it. Visitor IDs in private windows live for the session only and are flagged incognito: true on the resolution object.

Ad Blocker Detection

Detect when an ad blocker is interfering with the pixel and fall back to a server-side beacon endpoint at api.data-aviator.com/v4/beacon to preserve attribution.

Automatically Tracked Events

pageview — Initial render and SPA route changes
click — Any click on a tracked element
scroll — Throttled scroll depth (25/50/75/100%)
deep_scroll — User reached the bottom 10% of content
engagement — Sustained interaction (mouse + keyboard heuristics)
performance — Core Web Vitals: LCP, FID, CLS, INP
tab_visibility — Tab focus / blur
exit — Page unload with reason flag
exit_intent — Mouse trajectory leaving viewport
idle — 60s of no input
spa_navigation — Same-page route change
error — Uncaught JS exceptions
video — HTML5 video play / pause / complete
file_download — Click on a file-extension link
form_submit — Any form submission
clipboard — Copy event with element context

Custom Event Taxonomy

Fire any event you want. The pixel exposes a global dataAviator object once loaded.

track.js

// Track a domain-specific event with arbitrary properties
dataAviator.track('plan_upgraded', {
  from: 'free',
  to: 'pro',
  mrr_delta: 49,
  payment_method: 'card'
});

// Identify a known user — links visitor_id to your CRM record
dataAviator.identify('user_8a2c91', {
  email: 'jane@example.com',
  company: 'Acme Inc'
});

Deep Content Intent Tracking

For long-form content, the pixel reports content-section visibility, reading time per section, and re-read passes. Pipe these signals into your audience builder to identify high-intent readers vs. drive-by visitors.

SaaS & DaaS Usage Event Tracking

For application UIs, the pixel ships an opt-in mode that watches for high-value DOM mutations: feature flag exposure, paywall hits, premium feature taps, and trial-conversion CTAs. Wire these to POST /enrich/contact for server-side resolution at the moment of intent.

SPA Framework Compatibility

React / React Router

The pixel hooks history.pushState and history.replaceState directly. No router-specific integration is required — works with React Router v5, v6, and TanStack Router out of the box.

Lovable / Vite Apps

Drop the script tag in index.html. Vite's HMR is handled gracefully — events do not double-fire on hot reload.

Next.js

Use next/script with strategy="afterInteractive". Both App Router and Pages Router are supported.

Vue / Nuxt / Angular

Plain script tag in your index.html or root layout. Each framework's router triggers history changes that the pixel detects natively.

Shopify Integration

Drop the pixel into theme.liquid in the <head>. The pixel auto-detects Shopify's checkout context and emits cart_add, cart_remove, checkout_started, checkout_step, and order_completed events.

Shopify Checkout Extensibility

Checkout Architecture

Shopify's modern checkout runs in a sandboxed iframe with a separate JS context. Standard pixels can't run there. Data Aviator ships a Checkout Extension that you install via the Shopify Admin under Settings → Customer events.

Checkout Event Lifecycle

The extension subscribes to Shopify's checkout_started, checkout_address_info_submitted, checkout_contact_info_submitted, checkout_shipping_info_submitted, payment_info_submitted, and checkout_completed events.

Post-Purchase Upsell Tracking

If you use Shopify's post-purchase upsell page or a third-party app, install the extension on that page too. Events tagged step: 'post_purchase' are stitched to the same order_id.

Thank You Page Event Capture

The thank-you page is the highest-confidence resolution point. The extension fires order_completed with the full line-item array and pipes it into the resolution model.

Checkout Extensibility Limitations

Shopify restricts what runs in checkout for security reasons. Custom document queries, third-party fetch calls, and clipboard tracking are unavailable inside the checkout iframe. Use the post-purchase or thank-you pages for those signals.

Pixel Health Check

Verify Visitor Identification

Open your site, open DevTools Network panel, filter for api.data-aviator.com. You should see batched event POSTs every few seconds with a 200 OK response.

Confirm Event Batching

Inside the request payload, every event carries a stable visitor_id, a session_id, and a pixel_id matching your dashboard.

Test in Incognito

Open the site in a new private window. The pixel should fire with a fresh visitor_id and incognito: true on the visitor record.

Resolution Data Model

The resolution object is the heart of Data Aviator's identity resolution engine. It transforms anonymous website visitors into real people and companies with 50+ enriched data points. This object is returned in audience lookups, pixel lookups, and enrichment responses.

Object Schema

Every resolved visitor is described by a single resolution object. Fields are grouped by category for readability — they all sit at the top level of the object in the actual API response.

Identity

Field	Type	Description
person_id	uuid	Stable identifier for the resolved person across pixels and audiences
email	string	Verified primary email
email_md5	string	MD5-hashed email for ad-platform onboarding
email_sha256	string	SHA256-hashed email for clean-room matching
phone	string	Verified primary phone, raw format
phone_e164	string	E.164-formatted phone

Person

Field	Type	Description
first_name	string	Given name
last_name	string	Family name
middle_name	string	Middle name when known
gender	string	`male`, `female`, or `unknown`
age_range	string	5-year bucket, e.g. `35-39`
birthdate_year	integer	Year of birth when known

Address

Field	Type	Description
address_line_1	string	Street address
city	string	City
state	string	2-letter US state or ISO subdivision
postal_code	string	ZIP / postal code
country	string	ISO 3166-1 alpha-2
lat	float	Latitude (4 decimal precision)
lng	float	Longitude (4 decimal precision)

Company

Field	Type	Description
company_name	string	Company legal or trade name
company_domain	string	Primary web domain
company_industry	string	Standardized industry tag
company_size	string	Employee count bucket, e.g. `51-200`
company_revenue_range	string	Revenue bucket, e.g. `$10M-$50M`
company_linkedin_url	string	Public LinkedIn company page

Role

Field	Type	Description
job_title	string	Full job title
job_seniority	string	Standardized seniority: `ic`, `manager`, `director`, `vp`, `cxo`
department	string	Functional department, e.g. `marketing`, `engineering`

Online Presence

Field	Type	Description
linkedin_url	string	Personal LinkedIn profile
twitter_url	string	X / Twitter profile when known
facebook_url	string	Public Facebook profile when known

Visitor Signals

Field	Type	Description
first_seen	timestamp	First time the pixel saw this visitor
last_seen	timestamp	Most recent activity
visit_count	integer	Total distinct visits
session_count	integer	Total distinct sessions
device_type	string	`desktop`, `mobile`, `tablet`
browser	string	Browser family
os	string	Operating system

Intent

Field	Type	Description
intent_score	float	0.0-1.0 likelihood of buying intent
intent_topics	array<string>	Topical interest tags
last_event	object	The most recent custom event with timestamp
event_history	array<object>	Up to 50 recent events (Pixel Lookup V4 only)

Confidence

Field	Type	Description
match_confidence	float	0.0-1.0 confidence in the resolution match
match_source	string	Which data partner produced the match
verified_at	timestamp	Last verification of identity fields

Example Resolution Object

resolution.json

{
  "person_id": "4d8f2c11-7e9b-4a1f-9b34-3a1e2f6c8d11",
  "email": "j.doe@acme.com",
  "first_name": "Jane",
  "last_name": "Doe",
  "job_title": "VP of Marketing",
  "job_seniority": "vp",
  "company_name": "Acme Inc",
  "company_domain": "acme.com",
  "company_size": "201-500",
  "city": "Austin",
  "state": "TX",
  "intent_score": 0.84,
  "intent_topics": ["marketing-automation", "intent-data"],
  "match_confidence": 0.92,
  "match_source": "composite",
  "verified_at": "2026-04-18T11:24:09Z"
}

Field availability

Not every field populates for every visitor. Match rates vary by region, device type, and whether the visitor has consented to identity resolution. Treat every field as optional and check for presence before using it downstream.

Audience

Audiences are persisted, filterable cohorts built on top of resolved visitors and enriched contacts. Use them as the unit of activation for ad platforms, ESPs, and outbound workflows.

GET/audiences

Get Audiences

List all audiences in your workspace, paginated.

Query Parameters

Param	Type	Description
page	integer	Page number, 1-indexed. Default 1.
page_size	integer	Records per page. Default 100, max 1000.
q	string	Optional filter on audience name.

cURL

curl --request GET \
  --url 'https://api.data-aviator.com/audiences?page=1&page_size=50' \
  --header 'X-Api-Key: YOUR_API_KEY'

POST/audiences

Create Audience

Create a new filtered audience. Audiences populate asynchronously — poll GET /audiences/{id} for status.

Body Parameters

Field	Type	Description
namerequired	string	Display name for the audience.
description	string	Free-text description.
filtersrequired	object	Filter expression (see Filter Reference below).
pixel_id	uuid	Restrict to visitors of a specific pixel.

cURL

curl --request POST \
  --url 'https://api.data-aviator.com/audiences' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "VPs of Marketing — SaaS — US",
    "description": "Decision-makers at SaaS companies",
    "filters": {
      "job_seniority": ["vp", "cxo"],
      "department": ["marketing"],
      "company_industry": ["software"],
      "country": ["US"]
    }
  }'

POST/audiences/preview

Preview Audience

Get an estimated record count for a filter expression without persisting an audience. Useful for sizing before committing to an audience build.

Body Parameters

Field	Type	Description
filtersrequired	object	Same filter shape as Create Audience.
pixel_id	uuid	Optional pixel scope.

POST/audiences/custom

Create Custom Audience

Build an audience from a list of seed identifiers (emails, phones, or visitor IDs) you already have. Each seed is matched against the resolution graph and enriched with the full resolution object.

Body Parameters

Field	Type	Description
namerequired	string	Display name.
seed_listrequired	array<string>	Up to 100,000 seeds per request. Email, phone, or visitor_id strings.
seed_type	string	`email`, `phone`, `visitor_id`, or `auto` (default).
description	string	Free-text description.

GET/audiences/{id}

Audience Lookup

Retrieve an audience and optionally its member resolution objects.

Path Parameters

Param	Type	Description
idrequired	uuid	The audience identifier.

Query Parameters

Param	Type	Description
include	string	Set to `members` to return resolution objects alongside metadata.
page	integer	For paginated members.
page_size	integer	Default 100, max 1000.

DELETE/audiences/{id}

Audience Delete

Permanently delete an audience and its associated member graph. This action is irreversible.

Path Parameters

Param	Type	Description
idrequired	uuid	The audience identifier.

GET/audiences/{id}/attributes

Audience Attributes

Get an aggregated demographic, firmographic, and intent rollup of an audience without retrieving individual members.

Path Parameters

Param	Type	Description
idrequired	uuid	The audience identifier.

Returns counts and percentage distributions across job seniority, department, company size, industry, country, and top intent topics.

Enrichment

Take a partial identifier and return a full resolution object. Use the synchronous endpoint for one-off lookups during a request, or the job endpoints to enrich large lists in the background.

POST/enrich/contact

Enrich Contact

Synchronous enrichment. Pass at least one identifier and get back the full resolution object. Latency is typically under 400ms.

Body Parameters

Field	Type	Description
email	string	Email address. Provide one of email, phone, or linkedin_url.
phone	string	Phone in E.164 or raw format.
linkedin_url	string	LinkedIn profile URL.
pixel_id	uuid	Optional. Constrains the resolution graph to a specific pixel's visitor history.
fields	array<string>	Optional. Limit returned fields for smaller payloads.

cURL

curl --request POST \
  --url 'https://api.data-aviator.com/enrich/contact' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "j.doe@acme.com"
  }'

POST/enrich/jobs

Create Enrichment Job

Submit a list of seeds for asynchronous enrichment. Useful for files larger than 10,000 records or when you want results delivered to a webhook.

Body Parameters

Field	Type	Description
namerequired	string	Display name for the job.
seed_listrequired	array<string>	Up to 1,000,000 seeds per job.
seed_type	string	`email`, `phone`, `linkedin_url`, or `auto`.
match_threshold	float	Minimum match_confidence to include a result. Default 0.7.
webhook_url	string	Optional URL Data Aviator will POST to when the job completes.

GET/enrich/jobs

Get Enrichments

List enrichment jobs and their statuses.

Query Parameters

Param	Type	Description
page	integer	Page number. Default 1.
page_size	integer	Default 100, max 1000.
status	string	Filter by `queued`, `running`, `completed`, or `failed`.

Pixel

Pixels are the per-property tracking targets that emit events into the resolution engine. Each domain or app you want to track gets its own pixel.

GET/pixels

Get Pixels

List all pixels in your workspace.

Query Parameters

Param	Type	Description
page	integer	Page number. Default 1.
page_size	integer	Default 100, max 1000.

POST/pixels

Create Pixel

Create a new pixel. The returned id is what you embed in the install snippet.

Body Parameters

Field	Type	Description
namerequired	string	Display name.
domainrequired	string	Apex domain or hostname this pixel is authorized for.
tracking_options	object	Optional toggles: `track_clicks`, `track_scroll`, `track_video`, `track_clipboard`.

GET/pixels/{id}

Pixel Lookup

Retrieve a pixel and its standard summary metrics — total visitors, resolved visitors, and 7-day trends.

Path Parameters

Param	Type	Description
idrequired	uuid	The pixel identifier.

Query Parameters

Param	Type	Description
window	string	`7d`, `30d`, or `90d`. Default `7d`.

GET/pixels/{id}/v4

Pixel Lookup (V4)

Enhanced lookup that returns the full V4 Super Pixel event taxonomy: per-event-type counts, top custom events, deep content intent rollups, and SaaS usage signals. Use this when you've upgraded to the v4 SDK and want to surface the full event surface.

Path Parameters

Param	Type	Description
idrequired	uuid	The pixel identifier.

Query Parameters

Param	Type	Description
include_event_history	boolean	If true, returns the last 50 raw events per resolved visitor.
window	string	`7d`, `30d`, or `90d`.

DELETE/pixels/{id}

Pixel Delete

Soft-delete a pixel. Stops new event ingestion immediately. Historical resolution objects remain accessible for 90 days, then are pruned.

Path Parameters

Param	Type	Description
idrequired	uuid	The pixel identifier.

Remove the install snippet

Deleting a pixel does not remove the script tag from your site. Pull the install snippet from your HTML before or after deletion to stop in-browser activity.

Webhooks

Receive real-time event pushes from Data Aviator at endpoints you control. Use webhooks to trigger downstream automations the moment an audience populates, an enrichment job completes, or a high-intent visitor resolves on your site.

Event-Driven

Subscribe to specific events. Each delivery is a single event payload, not a polling response.

Signed & Secure

Every payload is signed with HMAC-SHA256 using your secret. Verify before processing.

Automatic Retries

Failed deliveries retry with exponential backoff for 24 hours. Stable to transient outages.

Configuration

Configure webhooks two ways: through your Data Aviator dashboard at build.data-aviator.com, or programmatically via the /webhooks resource (configuration UI in dashboard recommended for most users).

Event Types

Event	When it fires
audience.created	An audience has been created and queued for population.
audience.populated	Audience is fully populated and ready to query.
enrichment.completed	An enrichment job has finished. Payload includes a download URL.
pixel.visitor_resolved	A previously anonymous visitor was resolved to a person.
pixel.event_received	(High-volume — opt-in only) A pixel event of a watched type was received.

Payload Structure

payload.json

{
  "id": "evt_8a2c91",
  "event": "pixel.visitor_resolved",
  "created_at": "2026-04-25T18:14:09Z",
  "workspace_id": "ws_2f4d11",
  "data": {
    "pixel_id": "4d8f2c11",
    "resolution": { /* full resolution object */ }
  }
}

Webhook Headers

Header	Description
X-Data-Aviator-Signature	HMAC-SHA256 signature of the raw body, hex-encoded.
X-Data-Aviator-Event	The event type, mirrored from the payload.
X-Data-Aviator-Delivery-Id	Unique per-delivery ID. Idempotency key.
X-Data-Aviator-Timestamp	Unix timestamp of the delivery, used in signature derivation.

Signature Verification

verify.js (Node)

const crypto = require('crypto');

function verifySignature(rawBody, headerSig, secret, timestamp) {
  const signed = `${timestamp}.${rawBody}`;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(signed)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(headerSig)
  );
}

Retry Behavior

Data Aviator considers any 2xx response a successful delivery. Anything else triggers retry with exponential backoff: 30s, 2m, 10m, 1h, 6h. After 5 failed attempts over 24 hours the delivery is marked failed and the payload is preserved in the dashboard for manual replay.

Best Practices

Use HTTPS endpoints

Webhooks deliver over HTTPS only. Self-signed certs and HTTP URLs are rejected at configuration time.

Respond quickly, process asynchronously

Acknowledge with 2xx within 5 seconds, then push the payload onto a queue for downstream work. Do not block the webhook response on slow third-party calls.

Always verify signatures

Without signature verification, your endpoint is open to spoofing. Verify before trusting any field in the payload.

Handle duplicate deliveries

Retries can produce duplicates. Use X-Data-Aviator-Delivery-Id as an idempotency key on your side.

Log raw payloads

Keep raw bodies for at least 7 days in case of replay or debugging. The dashboard preserves recent deliveries but raw retention is on you.

Rotate secrets periodically

Rotate webhook signing secrets every 90 days through the dashboard. Both old and new secrets are honored during the rotation window.

Testing Webhooks

1. Use webhook.site for inspection

Paste a webhook.site URL into the dashboard for a sandbox endpoint that captures and displays every delivery. Useful for first-look payload inspection.

2. Use ngrok for local development

Run ngrok http 3000, paste the ngrok URL into your webhook config, and receive deliveries on your local dev server.

3. Replay from the dashboard

Every recent delivery has a Replay button in the dashboard's Webhook log. Use it to re-test signature verification or downstream parsing without waiting for a new event to fire.

API Quick Start

Five steps from zero to a working pixel and your first audience.

1. Get your API key

Sign in to build.data-aviator.com. Navigate to Settings → API Keys → Generate. Copy the key — it is shown once. Store it as a server-side secret. Never commit it to a public repo.

2. Verify authentication

Confirm your key works by listing pixels.

cURL

curl --request GET \
  --url 'https://api.data-aviator.com/pixels' \
  --header 'X-Api-Key: YOUR_API_KEY'

A 200 response confirms the key. A 401 means a missing or wrong header.

3. Create your first pixel

cURL

curl --request POST \
  --url 'https://api.data-aviator.com/pixels' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Marketing site — production",
    "domain": "yourcompany.com"
  }'

4. Install the v4 Pixel on your site

Take the id from the response and paste this snippet into the <head> of every page you want tracked.

snippet.html

<script async
  src="https://cdn.data-aviator.com/v4/pixel.js"
  data-pixel-id="YOUR_PIXEL_ID"></script>

5. Build your first audience

Wait 24-48 hours for the pixel to accumulate visitor data, then preview an audience to see resolved volume.

cURL

curl --request POST \
  --url 'https://api.data-aviator.com/audiences/preview' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "filters": {
      "job_seniority": ["vp", "cxo"],
      "company_size": ["201-500", "501-1000"]
    }
  }'

Once the preview count looks right, swap the URL to /audiences with a name field and persist the audience.

You're up and running

From here, explore the Audience, Enrichment, and Pixel references for the full surface area.

Error Codes

The Data Aviator API uses standard HTTP status codes. Authentication errors (401) return plain-text responses (e.g., "missing API key" or "invalid API key"). Other errors include a JSON body with a code and message.

Code	Status	Description	Resolution
200	OK	Request succeeded.	No action needed.
201	Created	Resource created successfully.	No action needed.
400	Bad Request	Invalid request parameters or body.	Check the request body against the expected schema. Validate that required fields are present and types match.
401	Unauthorized	Missing or invalid API key (X-Api-Key header).	Verify your X-Api-Key header is set correctly. Note: `Authorization: Bearer` and query params do NOT work — only the X-Api-Key header is accepted. Generate a new key from `build.data-aviator.com` if needed.
403	Forbidden	API key lacks permission for this resource.	Check your API key scopes and workspace membership.
404	Not Found	Resource does not exist or has been deleted.	Verify the UUID is correct. Resources soft-deleted within 90 days are recoverable through dashboard support.
409	Conflict	Resource state prevents the operation (e.g., duplicate domain on a pixel).	Check existing resources for collisions before retrying.
422	Unprocessable Entity	Body parses as JSON but fails business validation.	Read the `message` field. Common causes: invalid filter expression, malformed E.164 phone, mismatched seed_type.
429	Too Many Requests	Rate limit exceeded.	Backoff using `Retry-After` header. Default limits: 60 req/min per key, 600 req/hour. Contact support to lift.
500	Internal Server Error	Unexpected server error.	Retry with exponential backoff. If persistent, capture `X-Request-Id` from the response and contact support.
502	Bad Gateway	Upstream data partner unavailable.	Transient — retry after 30s.
503	Service Unavailable	Service is in maintenance or overloaded.	Retry after the `Retry-After` header value.

Error Response Body

For non-401 errors, the body is JSON with this shape:

error.json

{
  "code": "invalid_filter",
  "message": "Filter expression contains unknown field 'department_xyz'",
  "request_id": "req_2f4d11_8a2c91"
}

Tips & Troubleshooting

Common stumbling blocks and how to get past them quickly.

Authentication: Only X-Api-Key Works

Confirm your authentication uses the literal header name X-Api-Key. Authorization: Bearer, x-api-token, query params like ?api_key=, and Basic Auth all return 401 with a plain-text body. The error body is intentionally short — there is no JSON envelope on auth failures.

Subaccount API Access

Each subaccount workspace generates its own API key. There is no master-key impersonation. If you manage multiple subaccounts as an agency, each one needs its own key and its own header value when calling the API.

CORS Errors When Calling the API

The REST API does not support browser-side calls — your API key would be exposed. Always call the API from a server-side language. The pixel SDK handles browser-side event ingestion via a different path that does not require your secret key.

JSON Body Must Be Valid

Trailing commas, unquoted keys, and single-quoted strings all return 400. Run your payload through a JSON linter before sending if you're hand-editing.

Pagination for Large Datasets

Default page_size is 100. For initial data pulls, use page_size=1000 (the maximum) and iterate page until the response array is empty. Don't use offset-based paging beyond page=100; for deep pagination, prefer cursor-based endpoints (introduced in v4.5).

UUID Format for Resource IDs

Audience and pixel IDs are always RFC 4122 v4 UUIDs (36 chars with hyphens). If your platform strips dashes from UUIDs, restore them before passing to the API.

Pixel Not Tracking Visitors

Confirm the script loads (DevTools Network panel). Confirm batched event POSTs to api.data-aviator.com. If neither shows up, check for: ad blockers in the test browser (use a clean profile), Content-Security-Policy headers blocking the CDN, or a domain mismatch between the pixel's configured domain and the site you're loading.

Resolution Data Takes Time

Identity resolution is not synchronous. After the pixel sees a visitor, the resolution graph is enriched in batches that complete within 5-15 minutes for most visitors. Don't expect a freshly-installed pixel to return resolved visitors on its first day — give it 24-48 hours.

Rate Limiting Best Practices

The API permits 60 requests per minute per key. For bulk operations, use the /enrich/jobs endpoint instead of looping /enrich/contact. For listing endpoints, increase page_size to 1000 to reduce request volume by 10×.

SPA (Single Page Application) Tracking

The v4 Pixel auto-tracks SPA navigation by hooking history.pushState and history.replaceState. If you're seeing only initial pageviews and not subsequent route changes, you may be using window.location.assign for navigation (full reload) — that's already tracked as a fresh pageview. If you're using a non-standard router that bypasses History API, fire dataAviator.track('pageview') manually on each route change.

Platform Compatibility

Install the Data Aviator v4 Pixel on any web platform. The script tag works universally; some platforms have native UI for adding it.

Quick Comparison

Platform	Native UI	SPA Routing	Checkout	Notes
GoDaddy	✓	—	—	Add via Site Settings → Tracking
WordPress	✓	—	Plugin-dependent	Use header.php or a header injection plugin
Wix	✓	—	—	Custom Code panel, header position
Squarespace	✓	—	—	Code Injection → Header
Webflow	✓	—	—	Project Settings → Custom Code → Head
React / Next.js	Manual	✓	Manual	Use next/script with afterInteractive
Shopify	Theme + Extension	✓	✓	Install Checkout Extension separately

Select a Platform

GoDaddy

Sign in to your GoDaddy Website Builder. Open Site Settings → Tracking & Analytics. Paste the install snippet into the Header field. Save and republish the site.

WordPress

Two paths. Theme: edit header.php in your active theme and paste the snippet immediately before </head>. Plugin: install Insert Headers and Footers (or any equivalent), paste the snippet into the Header field, save. Plugin path survives theme updates.

Wix

Open the Wix Dashboard → Custom Code (under Settings). Click Add Custom Code. Paste the snippet, set Add Code to Pages to All pages, set Place Code in to Head. Save.

Squarespace

Open the Squarespace Admin → Settings → Advanced → Code Injection. Paste the snippet into the Header field. Save.

Webflow

Open Project Settings → Custom Code → Head Code. Paste the snippet. Save and publish to staging or production.

React / Next.js

For Next.js (App Router), use the <Script> component in your root layout.tsx with strategy="afterInteractive":

layout.tsx

import Script from 'next/script';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <Script
          src="https://cdn.data-aviator.com/v4/pixel.js"
          strategy="afterInteractive"
          data-pixel-id="YOUR_PIXEL_ID"
        />
      </body>
    </html>
  );
}

For plain Vite / Create React App, paste the script tag into public/index.html just before </head>.

Universal Script Tag

If your platform isn't listed, paste the snippet into any HTML page's <head>:

universal.html

<script async
  src="https://cdn.data-aviator.com/v4/pixel.js"
  data-pixel-id="YOUR_PIXEL_ID"></script>

SDK Evolution: v1.0 → v2.1.0

A version-by-version look at what the v4 Pixel SDK has gained over its lifetime, what changed under the hood, and what stayed the same.

Version Timeline

Version	Released	Headline
v1.0.0	2023-Q3	Initial public release. Pageview, click, scroll, form_submit.
v1.2.0	2024-Q1	Bugfix and CDN performance pass. Functionally identical to v1.0.
v1.5.0	2024-Q3	Engagement, performance, video, file_download events.
v2.0.0	2025-Q1	Full SPA navigation hooking. Identity persistence rewrite.
v2.1.0	2025-Q4	Brave/incognito/ad-blocker detection. Shopify Checkout Extension.

Key Finding: v1.0 and v1.2.0 Are Functionally Identical

If you're on v1.0 or v1.2.0, you have the same event surface. v1.2 was a non-semantic bump that focused on CDN delivery and bundle size, with no new tracking capabilities. Upgrade straight to v2.x for the meaningful gains.

Auto-Tracked Events: Full Comparison

Event	v1.0	v1.5	v2.0	v2.1
pageview	✓	✓	✓	✓
click	✓	✓	✓	✓
scroll	✓	✓	✓	✓
form_submit	✓	✓	✓	✓
engagement	—	✓	✓	✓
performance	—	✓	✓	✓
video	—	✓	✓	✓
file_download	—	✓	✓	✓
spa_navigation	—	—	✓	✓
tab_visibility	—	—	✓	✓
exit_intent	—	—	✓	✓
idle	—	—	✓	✓
deep_scroll	—	—	✓	✓
error	—	—	✓	✓
clipboard	—	—	—	✓
checkout (Shopify)	—	—	—	✓

SPA Navigation: The Biggest Improvement

Pre-v2.0, single-page apps required manual track('pageview') calls on every route change. v2.0 introduced direct history.pushState / history.replaceState hooking, so React Router, Next.js routing, Vue Router, and any other History-API-based router fire spa_navigation events automatically with full URL context.

Full Capability Matrix

Capability	v1.0	v1.5	v2.0	v2.1
Persistent visitor ID	✓	✓	✓	✓
Session management	basic	basic	rewritten	rewritten
Event batching	5s flush	3s flush	2s + beacon	2s + beacon
SPA hook	—	—	✓	✓
Brave detection	—	—	—	✓
Incognito flag	—	—	—	✓
Ad-blocker fallback	—	—	—	✓
Shopify Checkout Ext	—	—	—	✓
Bundle size (gzipped)	14kb	11kb	16kb	17kb

Browser Event Listeners

v1.x bound listeners on document.body. v2.x moved to capture-phase listeners on window for earlier interception and to play nicer with frameworks that aggressively re-render the DOM.

Unchanged Across All Versions

The single-script-tag installation pattern
The X-Api-Key auth model for the REST API
The base URL (https://api.data-aviator.com)
Resolution object schema (additive only — fields are added, never removed or renamed)
The 100/1000 default/max page size on list endpoints

Upgrade path

Upgrades are drop-in for any v1.x → v2.x transition. The script tag URL stays the same; the CDN serves the version your account is configured for. Switch versions through the dashboard at build.data-aviator.com → Settings → Pixel Version.