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

# List People

> Returns a paginated list of identified website visitors

To list everyone identified in a time window, add `visited_since` (and optionally
`visited_until`); `include_page_views=true` adds the pages each person viewed in
that window. This mode allows `limit` up to 250 and orders people by when their
record last changed, so follow `nextCursor` to the end and deduplicate by `id`.
See [Partners](https://docs.trywildcard.ai/partners.md) for details.

Each person includes stored acquisition attribution: `referrer`, `utmSource`,
`utmMedium`, `utmCampaign`, `utmTerm`, `utmContent`, and `campaignHistory`, alongside
`trafficType` and `adPlatform`. Missing scalar values are `null`; missing history
is `[]`. These fields may describe an earlier campaign rather than the latest
visit. Reading them does not collect or generate missing attribution.


## OpenAPI

````yaml GET /v1/people
openapi: 3.0.3
info:
  title: Wildcard API
  description: >
    Programmatic access to your Wildcard data — identified website visitors,

    companies, events, and analytics.


    ## Authentication

    Visitor-data endpoints require an `mk_live_...` data key in `X-API-Key`.

    Partner management endpoints under `/v1/partner/*` require your
    `pk_live_...`

    management key instead. `/v1/health` is public and requires no key.


    ```bash

    curl -H "X-API-Key: mk_live_your_key_here"
    https://api-v1.maverickintelligence.co/v1/people

    ```


    ## Data API Rate Limiting

    - **1,000 requests per hour** per customer (shared across all API keys)

    - Every response includes `X-RateLimit-Limit` and `X-RateLimit-Remaining`
    headers

    - When exceeded, you'll receive a `429` response with a `Retry-After` header


    ## Pagination

    List endpoints use cursor-based pagination. Pass the `nextCursor` from the
    response

    as the `cursor` query parameter to fetch the next page.


    ## Sorting

    Visitor lists are sorted by most recently seen first (`lastSeen`
    descending).

    Traffic pages sort by observed human and AI page views, then domain and
    path.

    Custom sorting is not yet supported — passing a `sort` or `order` query

    parameter returns `400 bad_request`. Custom sorting options will be
    available

    in a future version.
  version: 1.1.0
  contact:
    name: Wildcard Support
    email: support@trywildcard.ai
    url: https://trywildcard.ai
servers:
  - url: https://api-v1.maverickintelligence.co
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Traffic
    description: >-
      Per-page human and AI traffic, including anonymous activity and server
      collection
  - name: System
    description: API health and status
  - name: People
    description: Identified website visitors
  - name: Events
    description: Behavioral events (page views, clicks, scrolls)
  - name: Companies
    description: Companies identified from visitors
  - name: Statistics
    description: Aggregate analytics
paths:
  /v1/people:
    get:
      tags:
        - People
      summary: List people
      description: >
        Returns a paginated list of identified website visitors.

        Results are sorted by most recently seen first.


        **Partner accounts:** every person carries `trackedDomain` and

        `clientRef` identifying which client they visited. Narrow to one client

        with `domain`, `client_ref`, or `domain_group_id`. A domain-scoped API
        key sees only its own

        client's visitors and cannot widen that with a filter. A missing group

        returns 404; an empty group returns no visitors.


        **Email deliverability:** every person carries an `emailVerification`

        block and an `emailStatus` summary from the ZeroBounce verification

        cache. Use `exclude_bad_emails=true` to blank confirmed-bad addresses

        exactly as a verified CSV export does, and `email_status` to filter the

        result set. Neither triggers a live verification — see

        `emailVerification` in the schema for what that means for addresses no

        export has covered yet.
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/cursor'
        - $ref: '#/components/parameters/since'
        - $ref: '#/components/parameters/domain'
        - $ref: '#/components/parameters/client_ref'
        - $ref: '#/components/parameters/domain_group_id'
        - name: hot_leads_only
          in: query
          schema:
            type: boolean
          description: Filter to only ICP-matched hot leads
        - name: path
          in: query
          schema:
            type: string
            example: /pricing,/demo
          description: >
            Return only people who viewed at least one of these pages anywhere
            in their journey, not just the page they were identified on.
            Comma-separate for several. Paths are matched case-insensitively and
            ignore the host, query string and trailing slash, so `/Pricing/` and
            `https://acme.com/pricing?utm_source=x` both mean `/pricing`. An
            empty or invalid value returns `400 validation_error`.
        - name: email_status
          in: query
          schema:
            type: string
            example: valid,catch-all
          description: >
            Return only people with at least one address in the given
            deliverability statuses. Comma-separate for several. Valid values:
            valid, invalid, catch-all, unknown, spamtrap, abuse, do_not_mail —
            anything else returns 400. People with no email address at all never
            match, including on `unknown`.
        - $ref: '#/components/parameters/exclude_bad_emails'
        - name: visited_since
          in: query
          schema:
            type: string
            format: date-time
          description: >
            Return only people with an identified page view at or after this
            time (timezone required). Switches to visit-window mode: results
            ordered by record update time, limit up to 250, its own cursor. A
            person updated while paging can appear on a later page again;
            deduplicate by id.
        - name: visited_until
          in: query
          schema:
            type: string
            format: date-time
          description: >-
            Exclusive end of the visit window; default now. Requires
            visited_since. Window at most 31 days.
        - name: include_page_views
          in: query
          schema:
            type: boolean
            default: false
          description: >-
            With visited_since, add pageViews (in the window, oldest first, up
            to 200) and pageViewsTruncated to each person.
      responses:
        '200':
          description: List of people
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      allOf:
                        - $ref: '#/components/schemas/Person'
                        - type: object
                          properties:
                            pageViews:
                              type: array
                              description: Present with include_page_views=true
                              items:
                                type: object
                                properties:
                                  timestamp:
                                    type: string
                                    format: date-time
                                  url:
                                    type: string
                                  pageTitle:
                                    type: string
                                    nullable: true
                                  domain:
                                    type: string
                            pageViewsTruncated:
                              type: boolean
                              description: Present with include_page_views=true
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                  window:
                    type: object
                    description: Present in visit-window mode
                    properties:
                      visitedSince:
                        type: string
                        format: date-time
                      visitedUntil:
                        type: string
                        format: date-time
        '400':
          description: Bad request (invalid parameters)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (missing or invalid API key)
        '403':
          description: Partner account unavailable
        '404':
          description: Domain group not found in your account
        '429':
          description: Rate limit exceeded
          headers:
            Retry-After:
              $ref: '#/components/headers/Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    limit:
      name: limit
      in: query
      schema:
        type: integer
        default: 50
        minimum: 1
        maximum: 100
      description: Number of records per page
    cursor:
      name: cursor
      in: query
      schema:
        type: string
      description: Pagination cursor from the previous response's `nextCursor`
    since:
      name: since
      in: query
      schema:
        type: string
        format: date-time
      description: Only return records with `lastSeen` after this ISO 8601 date
    domain:
      name: domain
      in: query
      schema:
        type: string
      description: >
        Partner accounts only. Restrict results to one tracked client domain.
        Matches subdomains too, so `acme.com` includes `app.acme.com`. A
        domain-scoped API key cannot use this to reach beyond its own scope.
      example: acme.com
    client_ref:
      name: client_ref
      in: query
      schema:
        type: string
      description: >
        Partner accounts only. Restrict results to one client by the reference
        label set on its tracked domains. Case-insensitive. If a client has
        several domains registered, all of them are included.
      example: ACME-1
    domain_group_id:
      name: domain_group_id
      in: query
      schema:
        type: string
        pattern: ^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$
      description: >
        Partner domain group ID. Matches exact member hostnames (www aliases
        normalized), including any member site the person has visited.
        Intersects domain, client_ref, and the key's scope; never grants extra
        access. Empty group returns zero matches; missing/foreign group returns
        404; invalid ID returns 400. Keep this filter when following pagination
        cursors.
      example: acme
    exclude_bad_emails:
      name: exclude_bad_emails
      in: query
      schema:
        type: boolean
        default: false
      description: >
        Blank any email field whose address is confirmed undeliverable (invalid,
        spamtrap, abuse, do_not_mail), matching what a verified CSV export does.
        The person is still returned, and `emailVerification` still reports the
        status, so you can see why a field came back empty. Addresses that are
        catch-all, unknown, or not yet verified are kept. Off by default — it
        empties fields existing integrations already read.
  headers:
    X-Request-Id:
      schema:
        type: string
        format: uuid
      description: Unique request identifier for debugging
    X-RateLimit-Limit:
      schema:
        type: integer
      description: Maximum requests per hour
    X-RateLimit-Remaining:
      schema:
        type: integer
      description: Remaining requests this hour
    Retry-After:
      schema:
        type: integer
      description: Seconds until rate limit resets (only on 429 responses)
  schemas:
    Person:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
          nullable: true
          description: Raw primary email address
        businessEmail:
          type: string
          nullable: true
          description: Best classified business email (company-domain match preferred)
        personalEmail:
          type: string
          nullable: true
          description: Best classified personal email (gmail > outlook > yahoo)
        emailStatus:
          type: string
          enum:
            - valid
            - invalid
            - catch-all
            - unknown
            - spamtrap
            - abuse
            - do_not_mail
          description: >
            Deliverability status of the address you would actually contact
            (businessEmail, else personalEmail, else email). `unknown` when the
            address has not been verified yet.
        emailVerification:
          type: object
          description: >
            Cached ZeroBounce deliverability results, keyed by lowercased email
            address, covering every address in this response. Results come from
            the verification cache populated by verified exports — reading this
            endpoint never triggers a new verification, so an address that no
            export has covered reports `unknown` with a null `checkedAt`.
          additionalProperties:
            type: object
            properties:
              status:
                type: string
                enum:
                  - valid
                  - invalid
                  - catch-all
                  - unknown
                  - spamtrap
                  - abuse
                  - do_not_mail
              subStatus:
                type: string
                description: ZeroBounce sub-status detail (e.g. mailbox_not_found)
              checkedAt:
                type: string
                format: date-time
                nullable: true
                description: When this address was last verified; null if never
              stale:
                type: boolean
                description: >
                  True when the result is older than 90 days (or absent). Stale
                  entries are re-verified on the next verified export.
        firstName:
          type: string
          nullable: true
        lastName:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        company:
          type: string
          nullable: true
        location:
          type: string
          nullable: true
        region:
          type: string
          nullable: true
          enum:
            - USA
            - UK
            - EUR
            - Other
        linkedinUrl:
          type: string
          nullable: true
        phone:
          type: string
          nullable: true
          description: >-
            Best available phone number (DNC-filtered, matches dashboard
            display)
        profileImageUrl:
          type: string
          nullable: true
          description: Person's profile photo URL
        visitCount:
          type: integer
        firstSeen:
          type: string
          format: date-time
        lastSeen:
          type: string
          format: date-time
        isHotLead:
          type: boolean
        classifiedSeniority:
          type: string
          nullable: true
        classifiedJobFunction:
          type: string
          nullable: true
        trafficType:
          type: string
          nullable: true
          description: How the visitor arrived (organic, paid, direct, referral)
        adPlatform:
          type: string
          nullable: true
          description: >-
            Ad platform if traffic type is paid (google, facebook, linkedin,
            etc.)
        referrer:
          type: string
          nullable: true
          description: >-
            Stored referrer, usually a URL. Some providers supply a serialized
            referrer object. Null when unavailable; not necessarily the referrer
            of the latest visit.
        utmSource:
          type: string
          nullable: true
          description: >-
            Stored attribution source, from campaign tags or an inferred
            referrer source when available.
        utmMedium:
          type: string
          nullable: true
          description: Stored campaign medium, such as cpc or email.
        utmCampaign:
          type: string
          nullable: true
          description: Stored campaign name.
        utmTerm:
          type: string
          nullable: true
          description: Stored campaign keyword or term.
        utmContent:
          type: string
          nullable: true
          description: Stored campaign content or creative label.
        campaignHistory:
          type: array
          description: >
            Recorded campaign touches, oldest first, retaining up to 20 entries.
            Consecutive touches with the same campaign and platform are
            deduplicated; this is not a complete visit history. Empty when
            unavailable. Attribution fields retain the last meaningful campaign
            touch and may differ from the latest visit. Reading the API does not
            generate missing attribution.
          items:
            type: object
            properties:
              campaign:
                type: string
              platform:
                type: string
              trafficType:
                type: string
              source:
                type: string
                description: Marketing attribution source, not the identity-data provider.
              timestamp:
                type: string
                format: date-time
        trackedDomain:
          type: string
          nullable: true
          description: >
            Partner accounts: the tracked client domain this visitor was
            identified on. Omitted for non-partner accounts.
        clientRef:
          type: string
          nullable: true
          description: >
            Partner accounts: the partner's own label for the client that owns
            this visitor. Empty when the domain has no reference set.
        companyData:
          type: object
          nullable: true
          properties:
            companyId:
              type: string
            name:
              type: string
            domain:
              type: string
            standardizedIndustry:
              type: string
            location:
              type: string
            employeeCount:
              type: integer
    Pagination:
      type: object
      properties:
        limit:
          type: integer
          description: Requested page size
        count:
          type: integer
          description: Number of items in this page
        nextCursor:
          type: string
          nullable: true
          description: Pass this as `cursor` to get the next page. Null when no more pages.
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - unauthorized
                - forbidden
                - not_found
                - rate_limit_exceeded
                - bad_request
                - validation_error
                - invalid_cursor
                - internal_error
            message:
              type: string
            status:
              type: integer
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'API key in format: mk_live_{40 hex chars}'

````

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