SOURCE_ID: track_website_visitors
NAME: Track Website Visitors (B2B)
CATEGORY: First-party

Identify the companies visiting your website. On create, Floqer issues a
tracking pixel for your domain; once you embed that pixel on your site,
Floqer resolves visitor traffic to company-level rows (firmographics +
visited pages) and makes them available to your workflows. This is a
pixel-driven, ongoing source — it only receives data after the pixel is
installed.

INDEX:
  1. Endpoints
  2. How the pixel works (data model)
  3. Lifecycle (ongoing, pixel-driven)
  4. Body shape (preview + create)
  5. Field catalogue
  6. Dynamic options
  7. How to configure end-to-end
  8. Key notes
  9. When to use

================================================================================
1. ENDPOINTS
================================================================================

Source identifier (used in every endpoint path): `track_website_visitors`.

  POST /api/v1/sources/track_website_visitors/preview
    Scope: sources:read
    Validates `active_domain` and returns an EMPTY result set. Preview cannot
    return rows because visitors are only identified after the pixel is
    installed (see §2). Use it only to confirm the domain is accepted. Does
    not consume Floqer credits.

  POST /api/v1/sources/track_website_visitors
    Scope: sources:write
    Creates the source AND issues a tracking pixel. Returns `source_instance_id`
    (UUID) plus `pixel_id` and `pixel_script`. You MUST embed `pixel_script`
    on your website for the source to ever receive data (see §2).

  GET /api/v1/sources/<source_instance_id>/data
    Scope: sources:read
    Paginated company-visitor rows. `<source_instance_id>` is the UUID returned by
    Create. Rows appear only after the pixel is installed and visitors
    arrive. Query: `page_no` (default 1), `page_size` (default 20, max 200).
    Source-agnostic; see concepts.txt §10.

  POST /api/v1/sources/<source_instance_id>/sync
    Scope: sources:write
    Connects the created source to a workflow. `<source_instance_id>` = UUID from
    Create. Body: { workflow_id, field_mapping, push_existing?, run? }.
    Source-agnostic; see concepts.txt §10.

  PATCH /api/v1/sources/<source_instance_id>/status
    Scope: sources:write
    Pause or resume the source. Body: {"status": "active"|"paused"}. Pausing
    stops the source from ingesting new identified visitors. Note: the pixel
    script remains embedded on your site until you remove it — to fully stop
    tracking, also remove `pixel_script` from your pages.

No connection is required. There is no dynamic-options endpoint for this
source today (see §6).

================================================================================
2. HOW THE PIXEL WORKS (DATA MODEL)
================================================================================

This source is driven by a tracking pixel, not by a search query:

  1. Create the source with your `active_domain`. The response includes
     `pixel_id` and `pixel_script`.

  2. Embed `pixel_script` on every page of your website you want tracked
     (typically just before </body>, like any analytics snippet).

  3. When a visitor loads a tracked page, the pixel reports the visit.
     Floqer resolves the visitor's network to a COMPANY and writes a row
     with that company's firmographics plus the page that was visited.

Because identification only happens after the pixel runs on real traffic:
  - Preview returns NO rows (it only validates the domain).
  - GET .../data is empty until the pixel is installed and visitors arrive.
  - Identification is company-level, not person-level. For person-level
    identification use `track_personal_website_visitors`.

================================================================================
3. LIFECYCLE (ONGOING, PIXEL-DRIVEN)
================================================================================

Track Website Visitors is an ongoing source. Once the pixel is installed it
keeps ingesting identified company visitors and appending them as rows.

  expiration_date  (create only, optional)
    Optional date string (YYYY-MM-DD or ISO-like). The source stops ingesting
    new visitors after this date. When omitted, the source has no near-term
    stop date. Accepted but ignored on preview.

There is no `frequency` — ingestion is event-driven by real page loads, not
a poll schedule.

================================================================================
4. BODY SHAPE (PREVIEW + CREATE)
================================================================================

Field names are snake_case. Unknown top-level keys are rejected with 400 —
the body is strict.

Preview accepts:
  active_domain        required: valid domain (e.g. "yourcompany.com")

Create accepts:
  active_domain        required: valid domain
  name                 required: display name for the new source
  expiration_date      optional: valid date string

Domain rule: `active_domain` must be a bare domain like `yourcompany.com`
(no scheme, no path). Values that fail this check return 400.

Example preview body:

  { "active_domain": "yourcompany.com" }

Example create body:

  {
    "name": "Companies visiting our site",
    "active_domain": "yourcompany.com",
    "expiration_date": "2027-01-01"
  }

Preview response envelope:

  {
    "status": 200,
    "data": {
      "data": [],
      "metadata": { "total_results": 0 }
    }
  }

  Always empty — preview cannot return rows for a pixel-driven source.

Create response envelope:

  {
    "status": 201,
    "data": {
      "source_instance_id": "<uuid>",
      "name": "Companies visiting our site",
      "created_at": "2026-05-27T12:00:00.000Z",
      "pixel_id": "<pixel-id>",
      "pixel_script": "<script>...</script>"
    }
  }

  `pixel_script` is the snippet you embed on your website. Until it is
  installed and pages are loaded by real visitors, the source receives no
  data.

================================================================================
5. FIELD CATALOGUE
================================================================================

  active_domain (string) — required
    The website domain to track, as a bare domain (no scheme/path).
    Example: "yourcompany.com"

  name (string) — required on create only
    Human-readable display name for the source.

  expiration_date (string) — optional, create only
    Stop ingesting visitors after this date. Accepted but ignored on
    preview.

Create response fields (read-only):
  source_instance_id   UUID of the created source
  pixel_id             Identifier of the issued tracking pixel
  pixel_script         The script snippet to embed on your website

Imported row fields (read-only — populated only after the pixel is installed
and visitors are identified). Each row is company-level and carries the
visited page plus the resolved company's firmographics, including:

  Visit
    visited_url          The page on your site that was visited
  Company
    name / company       Company name
    domain               Company domain
    website              Company website
    industry             Industry
    description          Company description
    founded_year         Year founded
    employee_range       Headcount range
    annual_revenue       Estimated annual revenue
    total_funding        Total funding raised (when available)
    phone                Company phone
    logo                 Company logo URL
  Location
    country, country_code, state, state_code, city, postal_code, street
  Social profiles
    linkedin, twitter, facebook, crunchbase (handles / URLs when available)

  Exact keys depend on the resolved company; always run sync after some real
  traffic has been identified, and inspect GET .../data to confirm the keys
  present before finalising `field_mapping`.

================================================================================
6. DYNAMIC OPTIONS
================================================================================

None. `active_domain` is a free-form domain string. There is no
`POST /api/v1/sources/track_website_visitors/options/<field_name>` endpoint.

================================================================================
7. HOW TO CONFIGURE END-TO-END
================================================================================

  Step 1 — (Optional) Validate the domain
    POST /api/v1/sources/track_website_visitors/preview
    Body: { "active_domain": "yourcompany.com" }
    Returns an empty result set; a 200 confirms the domain is accepted.

  Step 2 — Create the source and get the pixel
    POST /api/v1/sources/track_website_visitors
    Body: { "name": "...", "active_domain": "yourcompany.com" }
    Response includes `source_instance_id`, `pixel_id`, and `pixel_script`.

  Step 3 — Install the pixel (REQUIRED)
    Embed the returned `pixel_script` on every page of your site you want
    tracked. Without this, the source never receives data.

  Step 4 — Sync the source into a workflow
    POST /api/v1/sources/<source_instance_id>/sync   ( <source_instance_id> = UUID from Step 2 )
    Map workflow inputs to company-row fields (common: `input.company`,
    `input.domain`, `input.industry`, `input.visited_url`). Because rows
    arrive over time, set `push_existing` according to whether you want a
    backfill. See concepts.txt §10.

  Step 5 — Watch rows arrive
    GET /api/v1/sources/<source_instance_id>/data?page_no=1&page_size=20
    Rows appear as the pixel identifies real visitors.

================================================================================
8. KEY NOTES
================================================================================

- No connection is required.
- Pixel-driven: the source receives NO data until `pixel_script` is embedded
  on your site and pages are loaded by real visitors.
- Preview always returns an empty result set — it only validates the domain.
- Identification is COMPANY-level. For person-level visitor identification,
  use `track_personal_website_visitors`.
- `active_domain` must be a bare domain (no scheme/path), or create/preview
  return 400.
- Pausing the source stops ingestion, but the embedded `pixel_script` keeps
  running on your site until you remove it; remove the snippet to fully stop
  tracking.
- `expiration_date` is optional; omit it for an open-ended monitor.

================================================================================
9. WHEN TO USE
================================================================================

- De-anonymise website traffic: turn unknown visitors into named companies
  for sales follow-up.
- Account-based marketing: detect when target accounts visit, then trigger a
  workflow to alert reps or enroll the account in a play.
- Intent scoring: combine visited pages with firmographics to prioritise
  accounts showing buying interest.

When you want to identify individual people (not just companies) visiting a
site, use `track_personal_website_visitors`.

================================================================================

Last updated: 2026-06-02. Reference: https://floqer.com/docs/reference