> ## 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.

# Partners

> Provision sites, organize customer groups, and read their visitors through the API

Use one Wildcard partner account for all the sites your platform creates. Register
each site as a tracked domain, organize related sites into a domain group, and
request visitors for that group. You do not need a new Wildcard account or login
for every site.

## Use the right key

Both keys belong to your Wildcard account. Store them as secrets in **your own
site-builder backend**. Neither key belongs in a customer's page or tracking snippet.

| Key | Where to get it | What it does |
| - | - | - |
| `pk_live_...` | [Partner Dashboard](https://app.maverickintelligence.co/partner/dashboard) → **Domain Management API Key** | Manage domains and groups at `/v1/partner/*` |
| `mk_live_...` | [Developer API](https://app.maverickintelligence.co/api-keys) → **Create API Key** | Read visitors, journeys and page traffic; submit server page observations |

Send the appropriate key in `X-API-Key`. A management key does not authenticate
visitor-data requests; a data key does not manage domains. All examples below use
`https://api-v1.maverickintelligence.co`.

## Page traffic: people and AI agents

Use `GET /v1/traffic/pages` for page views by URL, including anonymous human
visitors, AI requests, and a breakdown by agent. It uses the same data key and
customer domain groups as the visitor APIs.

```bash theme={null}
curl -G "https://api-v1.maverickintelligence.co/v1/traffic/pages" \
  -H "X-API-Key: $WILDCARD_DATA_KEY" \
  --data-urlencode "domain_group_id=acme" \
  --data-urlencode "since=2026-10-01T00:00:00Z" \
  --data-urlencode "until=2026-10-08T00:00:00Z" \
  --data-urlencode "include_people=true"
```

Each `data` row has a `domain` and normalized `path`, with:

* `human.pageViews`: human-classified page loads, including unidentified visitors.
* `human.uniqueVisitors` and `human.sessions`: distinct recorded visitor and
  session IDs. Missing IDs are disclosed in `pageViewsWithoutVisitorId` and
  `pageViewsWithoutSessionId`; they are never invented from IP addresses.
* `ai.requests` and `ai.byAgent`: server-observed AI page requests, with stable
  agent IDs such as `openai-crawler`, `openai-crawler-user`,
  `anthropic-crawler`, and `perplexity-crawler`. `ai.pageViews` is the subset
  with a confirmed successful HTML response. A request-time hook can count
  visits without claiming that the later response succeeded.
* With `include_people=true`, `identifiedPeople` contains matched person IDs,
  names and company names. `human.identifiedPageViews` and
  `human.unidentifiedPageViews` partition the human count. Identification uses
  explicit browser identities and currently visible person records; it does
  not run enrichment. Unmatched or conflicting identities stay unidentified.
  Use `/v1/people/{id}` for the full identified profile.

`totals` covers every matching page, even when the response is paginated.
Unique visitors and sessions in `totals` are deduplicated across pages, so do
not sum page-level unique counts. A repeat page load is another page view;
it may belong to the same session and visitor.

Use `measure` to read only what you need. `measure=human` returns human
counts (and `identifiedPeople` with `include_people=true`) without reading
server AI observations; `measure=ai` returns AI agent counts without reading
human data. Fields belonging to the part you did not request are omitted, not
zeroed. The default, `measure=all`, returns both, as before. Splitting reads is
much faster for accounts that send server traffic, for example humans and
people every 15 minutes and AI agents hourly.

Filters: `domain` (exact hostname), `domain_group_id`, `client_ref`, `path`
(exact normalized path), `agent` (exact returned AI agent ID), `since`, and
`until`. These filters intersect with the key's scope; an apex filter never
includes a separately tracked subdomain. `agent` returns only matching
server AI traffic. Query strings, fragments and trailing slashes do not create
different pages. Different hostnames remain separate.

The default window is the last seven days. Supply timezone-aware ISO timestamps;
`since` is inclusive and `until` is exclusive, with a maximum 31-day window.
Use `limit=1..1000` (default 100) and repeat every filter with
`pagination.nextCursor` as `cursor`. Pagination pins the time window. Follow-up
batches requested within five minutes usually reuse the first batch's result,
so rows do not shift between batches; if it is no longer available, the batch
is recomputed and late arriving events can change results. This is a live
report, not a frozen export: for final numbers, query windows that ended a few
minutes ago. Every successful
response has `meta.complete=true`. If a window exceeds the bounded read or
identity budget, the API returns `422 window_too_large` with no partial totals.
Query shorter windows (daily if necessary). Identity lookup is capped at 100
distinct explicit email identities per request.
If the query exceeds its processing deadline, the API returns
`503 query_timeout` with a `Retry-After: 30` header; wait at least that
long, then retry with a smaller window.

### Collect AI requests from the server

The browser pixel provides human page activity. Crawlers that never execute
JavaScript need a server/edge collector. Install this on the actual website
request path; a script tag alone does not provide complete crawler coverage.

Submit page observations to `POST /v1/traffic/events` using a
**server-held, preferably domain-scoped data key**. Keep the original request
User-Agent. For response observations, include the actual successful response
status and HTML content type. Do not submit assets, API calls,
prefetch requests, redirects, failures, raw IPs, cookies or emails.

```json theme={null}
{
  "events": [{
    "eventId": "stable-request-id-reused-on-retry",
    "timestamp": "2026-10-18T18:00:00.000Z",
    "url": "https://acme-stories.example.com/pricing",
    "userAgent": "GPTBot/1.2",
    "method": "GET",
    "statusCode": 200,
    "contentType": "text/html"
  }]
}
```

For request-time hooks such as Next.js Proxy, send `observationType: "request"`
and omit `statusCode` and `contentType`. These count toward `ai.requests`, not
confirmed `ai.pageViews`. Only report actual page-route GETs; exclude prefetches,
assets and API routes. The default `observationType: "response"` requires a
successful HTML response. Choose one observation type per request, not both.

Send 1–100 events per batch. Timestamps must be within the past seven days
(up to five minutes of forward clock skew). `202` returns `accepted` and
`duplicates` counts. Retries must reuse the same event ID, timestamp and
payload. Changing a previously used ID/timestamp payload returns `409`.
A batch interrupted after some writes can be retried in full. This endpoint
records traffic only; it does not invoke providers, paid enrichment or delivery.
Paused, held, archived, unregistered and out-of-scope sites cannot submit traffic.

The [downloadable server collector](https://app.maverickintelligence.co/traffic-collector.mjs)
works with standard `Request`/`Response` objects. Call `recordPageResponse`
**after obtaining the actual response** and keep its promise alive with your
server platform's background-task mechanism. For example, a Cloudflare Worker:

```javascript theme={null}
import { recordPageResponse } from "./traffic-collector.mjs";

export default {
  async fetch(request, env, ctx) {
    const response = await fetch(request);
    if (env.WILDCARD_TRAFFIC_ENABLED === "true") {
      ctx.waitUntil(recordPageResponse(request, response, {
        apiKey: env.WILDCARD_TRAFFIC_KEY,
        allowedHosts: ["acme-stories.example.com"],
      }).then(result => {
        if (result.error) console.warn("Traffic delivery failed", result.status);
      }));
    }
    return response;
  },
};
```

If your site already runs a Next.js proxy (`src/proxy.ts`), use `recordPageRequest`
inside the existing page-route handler after redirect checks. This does not
need another proxy or a change to the page response:

```javascript theme={null}
event.waitUntil(recordPageRequest(request, {
  apiKey: process.env.WILDCARD_TRAFFIC_KEY,
  allowedHosts: ["the-registered-site-hostname.example.com"],
  isPageRequest: true,
}).then(result => {
  if (result.error) console.warn("Traffic delivery failed", result.status);
}));
```

Import the helper from the downloaded module. Run this only for explicitly
opted-in sites with a configured secret; keep it independent of any other
telemetry provider's enable switch. Preserve the existing route matcher and
response. Use the actual configured site hostname, never an unvalidated Host
header to construct the allowed-host list. This adapter skips prefetches,
RSC-only requests and API routes. It cannot see a final response status.

Set the key as a deployment secret and explicitly enable opted-in sites. The
collector strips query strings/fragments, skips non-HTML responses and
prefetches, and retries transient failures once with the same event identity.
This small adapter is best effort: monitor errors. For durable delivery or
high volume, enqueue observations and submit batches; honor `Retry-After` on
429\. The existing 1,000 requests/hour data API limit includes collection.

### Coverage and interpretation

Human counts default to browser observations. `human_source=server` selects
server-observed human page loads instead; it never adds the two sources.
Optional server `visitorId`/`sessionId` values must be opaque first-party IDs;
without them server unique visitor/session counts remain zero with missing-ID
counts reported. Identity matching is available for browser observations only.

AI request totals use server observations. `browserAiPageViews` separately exposes AI
observations made by the browser pixel, without double-counting them against
server requests. Other bots and unclassified requests have separate fields for
each source. `meta.coverage` reports observations and their most recent timestamp;
`aiCoverage=server_collection_not_observed` means zero AI traffic is **not**
evidence that no AI agents visited. Verify the collector on each installed site.

Agent names are **User-Agent claims**, not verified operator identities.
Human classification is a browser heuristic after known automation is excluded.
Spoofed User-Agents and agents indistinguishable from normal browsers remain
limitations. A human referral from ChatGPT is human traffic, not an AI visit.
Browser blockers, consent, installation coverage and data retention affect
observed totals. Server collection begins when installed; it cannot recreate
past crawler requests that were never collected.

## 1. Create one group per customer

For example, a customer with ten sites can have one group named `Acme`. Choose a
stable `groupId` from your own system so a retry does not create another group.
IDs are case-sensitive, 1–64 letters, numbers, underscores, or hyphens, beginning
with a letter or number. Names are 1–100 characters.

```bash theme={null}
curl -X POST "https://api-v1.maverickintelligence.co/v1/partner/domain-groups" \
  -H "X-API-Key: $WILDCARD_PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"groupId":"acme","name":"Acme"}'
```

The response is `{ "success": true, "group": { "groupId": "acme", "name":
"Acme", "domains": [], "createdAt": "...", "updatedAt": "..." } }`.
Creation returns `201`; retrying with the same ID and name returns `200`.
Omit `domains` in this creation call so retries preserve sites attached later.
A different payload for an existing ID returns `409`; use `PATCH` to change it.
Omit `groupId` only if you want Wildcard to generate an ID.

## 2. Register each new site and install its snippet

Call this from your backend whenever your site builder provisions a domain:

```bash theme={null}
curl -X POST "https://api-v1.maverickintelligence.co/v1/partner/domains" \
  -H "X-API-Key: $WILDCARD_PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"acme-stories.example.com","clientRef":"ACME-1","groupId":"acme"}'
```

The response includes `domain`, `customerId`, `pixelSnippet`, `status`, and
`trackingSyncPending`. Install the returned `pixelSnippet` in your site's shared
page template. Every site under your partner account uses the same partner
`customerId`; a domain or group ID is not a new Wildcard customer ID. Use the
returned snippet rather than constructing a different account ID per site.

`groupId` is optional. Supplying it attaches the newly registered site—or an
existing site you already own—to that group. The group must exist first. A
`clientRef` is a separate optional label for attribution; it does not create a group.

Check `GET /v1/partner/domains` for the site's status. Tracking is ready when the
site is active and `trackingSyncPending` is false. Registration does not override
an explicitly paused site or inactive account. Retry a `429` with backoff and
jitter. Inspect other errors before retrying; a conflict or limit failure needs
attention. A partial registration can be retried with the same domain and group.

The domain list returns `maxDomains`, your account's configured site limit. Groups
organize that allowance; creating a group does not increase it. A site can belong
to more than one group. Keep both API keys on your backend—the browser snippet
uses your account identifier without exposing either key.

## 3. Read visitors for a group

Use your **data key**, with `domain_group_id` in the query string:

```bash theme={null}
curl -H "X-API-Key: $WILDCARD_DATA_KEY" \
  "https://api-v1.maverickintelligence.co/v1/people?domain_group_id=acme&limit=100"
```

The filter matches the exact tracked hostnames in the group, normalizing `www.`
aliases. Add subdomains explicitly if they are separate sites. An apex member
such as `example.com` does not implicitly add `news.example.com` to that group.
A visitor matches if they have visited a member site.

You can combine `domain_group_id` with `domain` or `client_ref`. These constraints
intersect: one matching visit must satisfy them all, and an API key's domain
scope remains a hard limit. Groups are filters, not additional permissions.
An empty group returns no visitors; a missing group or a group belonging to
another partner returns `404`; a malformed group ID returns `400`.

List responses contain `data` and `pagination`. Keep the same filters and pass
`pagination.nextCursor` as `cursor` until there is no next cursor. A filtered page
may be empty while another cursor remains. Membership is read again on every
request, so deleting or emptying a group never falls back to your entire account.

```python theme={null}
import os
import requests

params = {"domain_group_id": "acme", "limit": 100}
headers = {"X-API-Key": os.environ["WILDCARD_DATA_KEY"]}
while True:
    response = requests.get(
        "https://api-v1.maverickintelligence.co/v1/people",
        headers=headers, params=params, timeout=30,
    )
    response.raise_for_status()
    page = response.json()
    for visitor in page["data"]:
        process_visitor(visitor)  # your application's import or delivery step
    cursor = page["pagination"].get("nextCursor")
    if not cursor:
        break
    params["cursor"] = cursor
```

To fetch only that group's journey events, use the same filter on
`/v1/people/{id}/events?domain_group_id=acme`. Filtering the people list does not
implicitly filter a later events request; send the group on both.

### Who was identified in a time window

To ask "who was identified on our sites between X and Y, and which pages did they
view?", add `visited_since` (and optionally `visited_until`, default now) to
`/v1/people`. Only people with at least one identified page view in that window
are returned. Add `include_page_views=true` to get those page views on each
person (`timestamp`, `url`, `pageTitle`, `domain`), oldest first, up to 200 per
person (`pageViewsTruncated` says when more exist).

```bash theme={null}
curl -G -H "X-API-Key: $WILDCARD_DATA_KEY" \
  "https://api-v1.maverickintelligence.co/v1/people" \
  --data-urlencode "visited_since=2026-11-18T16:00:00Z" \
  --data-urlencode "visited_until=2026-11-18T17:00:00Z" \
  --data-urlencode "include_page_views=true" \
  --data-urlencode "limit=250"
```

* Timestamps need a timezone; `visited_until` is exclusive; a window is at most 31 days.
* `limit` goes up to 250 in this mode. Follow `pagination.nextCursor` until it is
  absent; a page can hold fewer than `limit` people while a cursor remains.
* Results are ordered by when each person's record last changed, not by visit
  time. A person updated while you page can appear again on a later page;
  deduplicate by `id`. Nobody is skipped.
* Identifications can arrive after the visit, so re-reading a recent window can
  return more people. Re-read recent windows rather than treating them as final.
* This covers people identified by Wildcard's visitor identification. People
  identified only through your own identify calls appear in
  `/v1/traffic/pages?include_people=true`.
* The existing filters (`domain`, `client_ref`, `domain_group_id`, key scope,
  `hot_leads_only`, `email_status`, `path`, `since`) still apply. Page views are
  limited to the same sites.

## Maintain groups

* `GET /v1/partner/domain-groups` returns `{ "groups": [...] }` for your account.
* `PATCH /v1/partner/domain-groups` accepts `groupId` plus `name` and/or `domains`.
  The `domains` array **replaces** membership and may contain only sites already
  tracked by your partner account. An empty array empties the group.
* `DELETE /v1/partner/domain-groups` accepts `{ "groupId": "acme" }`. It removes
  the group without deleting sites or visitor history.

```bash theme={null}
curl -X PATCH "https://api-v1.maverickintelligence.co/v1/partner/domain-groups" \
  -H "X-API-Key: $WILDCARD_PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"groupId":"acme","domains":["acme-stories.example.com","acme-news.example.com"]}'
```

Paused sites remain valid members for historical visitor queries. Removed sites
are omitted from group membership. Changing a group never enables tracking.
Removing and then re-adding a site does not restore its old group membership; explicitly assign it again.

## Attribution on every record

People and events both carry the client they belong to:

```json theme={null}
{
  "eventType": "click",
  "timestamp": "2026-07-24T18:10:00Z",
  "url": "https://acme.com/product",
  "domain": "acme.com",
  "clientRef": "ACME-1"
}
```

Filter to one client with either `domain` or `client_ref`:

```bash theme={null}
curl -H "X-API-Key: mk_live_..." \
  "https://api-v1.maverickintelligence.co/v1/people?client_ref=ACME-1"
```

`domain` matches subdomains too — `acme.com` includes `app.acme.com`. If a client
has several domains registered under one `clientRef`, `client_ref` covers them all.

## Giving a client direct access

Rather than relaying data through your own product, you can issue each client an
API key **scoped to their domain only**. In the dashboard, go to
**Partner → Domains** and select **Enable API** on a client's domain.

The key is shown once. It behaves like any other API key, with one difference:
it can only ever read that one client's data.

* `/v1/people` returns only that client's visitors.
* `/v1/people/{id}/events` returns only events from that client's domain.
* Another client's person ID returns `404`, not an empty result — a scoped key
  cannot confirm that visitors outside its scope exist.
* Passing `?domain=` for someone else's domain returns nothing. The scope is a
  ceiling, not a default.

Each scoped key gets its own hourly rate limit, so one client's traffic never
consumes another's.

**Rotating and revoking.** Selecting *Rotate key* issues a new key and stops the
old one working immediately. *Revoke key* removes API access while leaving
tracking untouched.

## Reading a journey

A journey is the ordered stream of everything a visitor did:

```bash theme={null}
curl -H "X-API-Key: mk_live_..." \
  "https://api-v1.maverickintelligence.co/v1/people/{id}/events?limit=100"
```

Two things to build for:

**Journeys vary enormously.** One visitor has three events; another has several
thousand. Always page with `cursor` rather than assuming you got everything in one
response.

**Event shape is open-ended.** `eventId`, `sessionId`, `eventType`, `timestamp` and
`url` are always present. Everything else depends on the event type, and new event
types and fields appear as the tracking pixel evolves — without an API version
change. Treat `eventType` as an open set and ignore fields you do not recognise
rather than rejecting the payload.

Narrow to one kind of step with `event_type`:

```bash theme={null}
curl -H "X-API-Key: mk_live_..." \
  "https://api-v1.maverickintelligence.co/v1/people/{id}/events?event_type=form_submission"
```

## Getting journeys pushed instead of polled

If you'd rather receive activity than fetch it, subscribe to the
**`person.activity`** event on your partner webhook (Partner → Partner Webhook).

This event is **opt-in**. It is far higher volume than `person.identified` — one
engaged visitor fires dozens of events — so it is off by default and you must
switch it on deliberately.

Deliveries are **batched per visitor**: you get one call carrying that person's
new events as an array, not one call per event.

```json theme={null}
{
  "webhookId": "wh_a1b2c3d4e5f6a7b8",
  "event": "person.activity",
  "timestamp": "2026-07-24T18:10:04Z",
  "domain": "acme.com",
  "clientRef": "ACME-1",
  "data": {
    "person": { "id": "p_...", "email": "visitor@example.com" },
    "events": [
      { "eventType": "page_view", "timestamp": "2026-07-24T18:09:00Z", "url": "https://acme.com/" },
      { "eventType": "click", "timestamp": "2026-07-24T18:10:00Z", "url": "https://acme.com/", "clickElement": "Product" }
    ],
    "eventCount": 2,
    "truncated": false
  }
}
```

Events arrive **oldest-first**, so a journey reads forwards. If a visitor is
active enough to exceed the per-delivery cap, `truncated` is `true` — page the
API for the complete journey rather than assuming the batch is whole.

Payloads are signed with HMAC-SHA256 exactly like every other webhook event.


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