> ## Documentation Index
> Fetch the complete documentation index at: https://developer.lofty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Website traffic overview

> Visitors, page views and page views per visitor for the period, each with the change rate against the previous period (the previous value itself is not available yet and is null). Same numbers as the CRM Traffic Report. The period is at most 365 days and defaults to the last 30 days.



## OpenAPI

````yaml openapi/openapi.json GET /v2.0/website/analytics/traffic/overview
openapi: 3.0.1
info:
  title: Lofty Service Open APIs
  description: >-
    Lofty service API description


    ## Error status codes


    By default many failed requests answer HTTP 200 with an error body such as
    `{"code": ..., "message": "..."}`. Send the header `X-Error-Status: true` to
    have such a failed request answer with a 4xx or 5xx status instead. Most
    endpoints keep the same body; a few return a more detailed error body that
    carries a `code`. Decide success or failure from the HTTP status, not the
    body shape. Endpoints that report an outcome in a field of a successful
    response (for example `"success": false`) still answer 200.
  version: '1.0'
servers:
  - url: https://api.lofty.com
security: []
tags:
  - name: Tasks & Appointments V2
    description: >-
      Unified V2 API for lead tasks and appointments: list, create, read,
      update, finish, unfinish and delete. Tasks and appointments share the same
      taskId namespace; each endpoint resolves the target by ID regardless of
      underlying type.
  - name: Opportunity
    description: Operations about opportunity
  - name: Communication V2
    description: >-
      Fetch a single communication record (text / email / call) by its
      communication ID. Closes the webhook follow-up gap where only list-by-lead
      endpoints existed for text and email.
  - name: Website
    description: >-
      Read and manage the caller's own Lofty website: the traffic report shown
      in the CRM, Feature Areas (AI-generated community pages) and page SEO
      settings. The site itself is read through the Site Audit API.


      ### Access


      Available to website-only (Lofty Front) agents and to sites on the
      Hyperlocal Website package. Other callers get HTTP 403 with code 403001.
      Every call works on the caller's primary website; the analytics endpoints
      also accept a `siteId` the caller owns.


      ### Errors


      | code | meaning |

      |---|---|

      | 400001 | A parameter is missing or invalid; `message` names it |

      | 403001 | The caller is neither a website-only agent nor on a Hyperlocal
      site |

      | 403002 | The `siteId` does not belong to the caller |

      | 404001 | The caller has no primary website |

      | 404002 | The Feature Area does not exist on the caller's site |

      | 422001 | The website refused the request (e.g. the area already exists
      or the limit is reached); `message` says why |

      | 501001 | The capability is not available yet |

      | 100000 | The website service could not be reached (HTTP 502); retry
      later |

      | 502001 | The website service failed unexpectedly; retry later |
  - name: Vendor
    description: >-
      Team vendor directory: team members, sub-accounts and associated agents
      within the caller's team.
  - name: Mass Actions
    description: >-
      Bulk operations across many leads at once: mass SMS, mass email, bulk tag
      changes, bulk pipeline-stage changes. Each call creates an asynchronous
      plan and returns immediately - it does not wait for the sends/updates to
      complete.
  - name: Lead Routing
    description: >-
      Lead routing configuration: read and update routing rules and default
      (supplement) rules per business type, and list the members and roles
      available for assignment.
  - name: Lead Activity V2 API
    description: >-
      Unified lead activity timeline: returns call, text and email activities
      for a lead in chronological order, including both auto-captured and
      agent-logged entries.
  - name: Site Audit
    description: >-
      Read the facts an audit of the caller's own Lofty website is made of:
      overview, site-level SEO settings, pages with their SEO fields, one page's
      raw templates, navigation structure, robots / sitemap files and
      third-party integrations. Every section is wrapped as `{section, siteId,
      generatedAt, partial, data}`; `partial` is true when a part of the section
      could not be fetched: a technical file, or a page whose live fetch failed
      (its fetchError says why). The API reports, it does not score: conclusions
      and advice are the caller's.


      ### Access


      Available to website-only (Lofty Front) agents and to sites on the
      Hyperlocal Website package. Other callers get HTTP 403 with code 403001.
      Every call works on the caller's primary website.


      ### Errors


      | code | meaning |

      |---|---|

      | 400001 | A parameter is missing or invalid; `message` names it |

      | 403001 | The caller is neither a website-only agent nor on a Hyperlocal
      site |

      | 404001 | The caller has no primary website |

      | 404003 | The page does not exist on the caller's site |

      | 100000 | The website service could not be reached (HTTP 502); retry
      later |

      | 502001 | The website service failed unexpectedly, for example a timeout
      while checking the site's pages (HTTP 502, the message is generic); retry
      later |
  - name: Tasks & Appointments
    description: >-
      Agent tasks and lead appointments. Supports listing a lead's appointments,
      listing / reading / creating / updating / deleting tasks on a lead.
  - name: Transactions V2
    description: V2 transaction APIs.
  - name: Lead Manual Log
    description: >-
      Agent-recorded log of communications that happened outside the Lofty CRM
      (calls placed on a personal line, emails sent from another mailbox, SMS
      sent from another device). Three channels are supported: logCall,
      logEmail, logText. Direction fields are recorded from the agent's point of
      view: 'outbound' = agent -> lead, 'inbound' = lead -> agent. Persistence
      is asynchronous: a POST returns the new entry's ID once the write is
      enqueued, and the entry becomes readable after a short delay.
  - name: Calls
    description: >-
      Calls placed or received through the Lofty dialer. Supports fetching a
      recording URL, retrieving a single call record, and listing calls attached
      to a lead.
  - name: Agents V2
    description: >-
      Agent lifecycle management: deactivate an agent of the caller's team
      (frees the license seat, revokes sessions and tokens, keeps leads and data
      untouched) and reactivate a previously deactivated agent (re-occupies a
      seat and restores access without data loss). Deactivation is reversible
      and distinct from deletion.
  - name: Agent User
    description: >-
      Agent onboarding and team directory operations. Create a new agent under
      the caller's team and attach tags to existing agents.
  - name: Showings V2 API
    description: >-
      Create and maintain property showings on behalf of an integration partner:
      create a showing, list and read showings, reschedule, change status,
      cancel, and attach feedback.


      Statuses: requested, scheduled, in_progress, completed, denied, expired,
      cancelled. A showing created through the API keeps whatever status the
      partner last wrote - Lofty does not move it to in_progress / completed /
      expired by itself.


      Only showings created by the calling partner can be updated, cancelled or
      given feedback; showings created inside Lofty or by another partner are
      read-only (200130).


      Subscribe to webhook event type 13 (Showing) to be notified of
      createdShowing, updatedShowing and createdShowingFeedback events.
  - name: Calendar V2 API
    description: >-
      Unified V2 API for tasks and appointments on a lead: create, update,
      delete, finish, unfinish, query a paginated list, and find available
      meeting slots. Calendar IDs returned by POST /v2.0/calendar are composite
      strings of the form '`<numericId>`-task' or '`<numericId>`-appointment'
      and must be sent back as-is to the per-entry endpoints.
  - name: Lead System Logs
    description: Query a lead's system log.
  - name: Lead Transaction
    description: Operations about leads
  - name: Webhooks
    description: >
      Use webhooks to be notified about events that happen in a lofty account.


      Supported webhook event types (listId):


      | listId | Event Type | Description |

      |--------|-----------|-------------|

      | 1 | Agent Info | Agent created or updated |

      | 2 | Lead Info | Lead created, updated, or deleted |

      | 3 | Lead Activity | Lead site activity (e.g. SiteBrowse, SiteFavorite,
      SiteSearch) |

      | 4 | Listing Alert | Listing alert changed |

      | 5 | Transaction | Transaction created, updated, or deleted |

      | 6 | Call | Call event (MANUAL and LOGGED only, excludes AUTO) |

      | 7 | Email | Email event (MANUAL and LOGGED only, excludes AUTO) |

      | 8 | Text | Text message event (MANUAL and LOGGED only, excludes AUTO) |

      | 9 | Note | Note created, updated, or deleted |

      | 10 | Task | Task created, updated, finished, or deleted |

      | 11 | Appointment | Appointment created, updated, finished, or deleted |

      | 12 | Pipeline Change | Lead pipeline stage changed |

      | 13 | Showing | Showing created, updated or cancelled; showing feedback
      added |


      ### Notification Recipient Rules


      Here "team" means the entire Lofty client account (the organization), not
      the Lofty "Team add-on" product.


      Which subscribed users receive a callback depends on the subscription's
      delivery mode (`permissionMode`). In both modes, only users in the lead's
      account (team) who have subscribed to the event type are considered.


      **Assignment-based delivery — `permissionMode: 0` (default)**


      A subscriber receives the callback only for leads assigned to them or that
      they administer:

      - If the lead is a **hidden lead**, only the **assigned agent** receives
      the notification.

      - Otherwise, the subscriber receives it if they are the **assigned agent**
      of the lead, or a **Company Owner** or **Company Admin**.

      - All other subscribers do **not** receive the notification.


      **Ownership-based delivery — `permissionMode: 1`**


      A subscriber receives the callback for any lead they manage, regardless of
      who it is assigned to:

      - Every assignment-based case above still applies (assigned agent, Company
      Owner / Company Admin).

      - In addition, the subscriber receives the callback for any lead within
      their **ownership scope** — a lead owned by their **team** or **office**,
      or **personally owned** by them — even if it is assigned to someone else.

      - Hidden leads are still delivered only to users who manage them.


      Ownership-based mode is intended for team/account-level integrations that
      must cover every lead in their scope, not only assigned leads. Set
      `permissionMode` when creating the subscription (POST /v1.0/webhook); it
      defaults to `0`, so existing subscriptions are unaffected.


      ### Delivery Timing


      Webhooks are typically delivered within **1 minute** of the event being
      triggered. During periods of high traffic, delivery may be delayed, but
      will always be sent within **5 minutes**.


      For detailed callback payload structures, see [Webhook Event
      Payloads](/concepts/webhooks#event-payloads).
  - name: Notifications V2
    description: Operations for sending notifications to agents
  - name: Notes
    description: >-
      Free-text notes attached to a lead. Supports create, list, get-by-id,
      update and delete. Notes may be pinned to surface them at the top of the
      lead's timeline. System-generated notes (automated activity) are included
      on the list endpoint only when explicitly requested.
  - name: Listing
    description: >-
      Listing data access: retrieve published listings for a site feed (XML),
      and search active / sold listings by agent, office or MLS id.
  - name: Intelligent Features
    description: AI-powered features for lead analysis and communication
  - name: Leads
    description: >-
      Lead lifecycle operations: create / read / update / delete a lead, search
      leads by stage, source, tag, create time or update time, place an inquiry
      or property on a lead, list lead activities, resolve assignee by lead
      info, and handle Brokermint contact callbacks.
  - name: Saved Searches
    description: >-
      Read the property searches a lead has saved, together with how their
      listing alerts are delivered.


      A saved search and its listing alert are one object: the search conditions
      and the delivery cadence travel together.


      ### Coverage


      `criteria` is a fixed field set. Filters this version does not model yet
      are listed by name in `unmappedCriteria`, so a partially understood search
      can be told apart from a fully mapped one. Values of unmapped filters are
      not returned.


      ### Pausing alerts


      A paused search keeps its conditions and schedule; only the emails stop.
      Pausing sets the cadence to NEVER, the same as choosing Never in the CRM,
      so a paused search reads back as `INACTIVE`, with the cadence it replaced
      in `frequencyBeforePause`; resume restores the same cadence. Alerts also
      stay silent while the lead is unsubscribed from property alerts, whatever
      the cadence.


      ### Errors


      A request rejected by validation or by a business rule (missing or invalid
      field, duplicate search, recipient that is not the lead's, ...) answers
      HTTP 200 with `{"code": <error code>, "message": "..."}` instead of the
      saved search. Check `code` in the body rather than the HTTP status.
      Unknown ids answer HTTP 404 and leads the token user cannot see answer
      HTTP 403.


      | code | meaning |

      |---|---|

      | 20012 | A field is missing, invalid or not allowed; `message` names it |

      | 2000001 | A saved search of the lead already has the same filters |

      | 2000005 | The lead has no email address to send alerts to |

      | 2000011 | The saved search cannot be edited (created by the lead on the
      website) |

      | 100000 | Lofty could not complete the change; try again later |
  - name: Members
    description: >-
      Team member directory: look up members by user ID, by account (email), or
      list all members of the caller's team. Also supports retrieving the
      current user's profile.
  - name: Team Features
    description: >-
      Team-scoped metadata: lead tags, custom fields, and lead ponds. Supports
      listing existing entries, adding a new custom field, and retrieving a
      specific lead pond.
  - name: Sales Agents V2
    description: >-
      Sales Agent (AI Assistant) management: read the caller's assistant and
      quota, query leads followed by AI, mute leads, manage working-pool
      membership and plan tasks, and read Sales Agent settings.
  - name: Agent Organization
    description: >-
      Team organizational structure: read the caller's organization info, manage
      company and office records, and list permission profiles available to the
      team.
  - name: Communication
    description: >-
      Lead communication history and outbound messaging: list call / email /
      text history for a lead, search communications for an agent, and send SMS
      or email to a lead.
paths:
  /v2.0/website/analytics/traffic/overview:
    get:
      tags:
        - Website
      summary: Website traffic overview
      description: >-
        Visitors, page views and page views per visitor for the period, each
        with the change rate against the previous period (the previous value
        itself is not available yet and is null). Same numbers as the CRM
        Traffic Report. The period is at most 365 days and defaults to the last
        30 days.
      operationId: getTrafficOverview
      parameters:
        - name: siteId
          in: query
          description: >-
            Website to read. Defaults to the caller's primary website; must be a
            site the caller owns.
          required: false
          schema:
            type: integer
            format: int64
        - name: startDate
          in: query
          description: >-
            First day of the period, yyyy-MM-dd, in the agent's CRM time zone.
            Defaults to 29 days before endDate.
          required: false
          schema:
            type: string
        - name: endDate
          in: query
          description: Last day of the period, yyyy-MM-dd. Defaults to today.
          required: false
          schema:
            type: string
        - name: Authorization
          in: header
          description: Bearer [access_token]
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrafficOverview'
        '401':
          description: Missing or invalid authentication token.
        '403':
          description: >-
            The caller is not a website-only agent, the site is not on the
            Hyperlocal package, or the site is not the caller's.
components:
  schemas:
    TrafficOverview:
      type: object
      properties:
        startDate:
          type: string
        endDate:
          type: string
        timeZone:
          type: string
        visitors:
          $ref: '#/components/schemas/MetricWithChange'
        pageViews:
          $ref: '#/components/schemas/MetricWithChange'
        pageViewsPerVisitor:
          $ref: '#/components/schemas/MetricWithChange'
    MetricWithChange:
      type: object
      properties:
        value:
          type: number
          format: double
        lastValue:
          type: number
          format: double
        changeRate:
          type: number
          format: double

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.