SOURCE_ID: track_personal_website_visitors
NAME: Track Personal Website Visitors
CATEGORY: First-party

Identify the individual people 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 person-level rows (name, title,
email, company, visited pages) and makes them available to your workflows.
This is a pixel-driven source — it only receives data after the pixel is
installed.

INDEX:
  1. Endpoints
  2. How the pixel works (data model)
  3. Lifecycle (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_personal_website_visitors`.

  POST /api/v1/sources/track_personal_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_personal_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). Create
    consumes Floqer credits.

  GET /api/v1/sources/<source_instance_id>/data
    Scope: sources:read
    Paginated person-visitor rows. `<source_instance_id>` is the UUID returned by
    Create. Rows appear only after the pixel is installed and visitors are
    identified. 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 to a PERSON and writes a row with that
     person's contact and company details plus the page they 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 person-level. For company-level identification use
    `track_website_visitors`.

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

Track Personal Website Visitors keeps ingesting identified people for as
long as the pixel is installed and the source is active. There is no
`frequency` (ingestion is event-driven by page loads) and no
`expiration_date` field on this source — to stop tracking, pause the source
and remove the embedded pixel script from your site.

================================================================================
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

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": "People visiting our site",
    "active_domain": "yourcompany.com"
  }

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": "People 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.

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 person-level:

  Contact
    firstName            Visitor's first name
    lastName             Visitor's last name
    email                Best available email (business, then personal)
    businessEmail        Business email, when known
    personalEmail        Personal email, when known
    title                Job title
  Person
    location             Person location text
    department           Department
    seniority            Seniority level
  Company
    company              Company name
    companyDomain        Company domain
    companyLinkedinUrl   Company LinkedIn URL
    industry             Industry
    country              Country
  Visit (present on page-visit events)
    pageUrl              The page on your site that was visited
    pageTitle            Title of the visited page
    referrer             Referring URL
    firstVisitAt         First visit timestamp
    lastVisitAt          Most recent visit timestamp
    utmSource / utmMedium / utmCampaign / utmContent / utmTerm
                         UTM parameters captured on the visit
  Meta
    segmentName          Segment label, when assigned
    segmentId            Segment identifier, when assigned

  Some fields are populated only on certain visitor events; run sync after
  some real traffic has been identified and inspect GET .../data to confirm
  which keys are 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_personal_website_visitors/options/<field_name>`
endpoint.

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

  Step 1 — (Optional) Validate the domain
    POST /api/v1/sources/track_personal_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_personal_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 person-row fields (common: `input.firstName`,
    `input.lastName`, `input.email`, `input.title`, `input.company`,
    `input.pageUrl`). 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 PERSON-level. For company-level visitor identification,
  use `track_website_visitors`.
- `active_domain` must be a bare domain (no scheme/path), or create/preview
  return 400.
- Create consumes Floqer credits; insufficient balance returns 402.
- 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.

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

- De-anonymise website traffic at the person level: turn unknown visitors
  into named contacts with email and title for direct outreach.
- Warm inbound: trigger a workflow when an identified person visits a
  high-intent page (pricing, demo, careers).
- Lead enrichment: feed identified visitors into a workflow that enriches and
  scores them before routing to sales.

When you only need company-level identification, use
`track_website_visitors`.

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

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