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

# Register a Partner Domain

> Registers a site under the authenticated partner account and returns its installation snippet. Optional groupId attaches the new or existing owned site to that group. A group must exist first. Never creates a separate customer account or overrides paused tracking. Retry 429 with backoff.



## OpenAPI

````yaml POST /v1/partner/domains
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/partner/domains:
    post:
      tags:
        - Partner Management
      summary: Register a partner domain
      description: >-
        Registers a site under the authenticated partner account and returns its
        installation snippet. Optional groupId attaches the new or existing
        owned site to that group. A group must exist first. Never creates a
        separate customer account or overrides paused tracking. Retry 429 with
        backoff.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - domain
              properties:
                domain:
                  type: string
                  description: Hostname only, without scheme or path.
                clientRef:
                  type: string
                  description: Optional attribution label for your customer.
                groupId:
                  type: string
                  description: Optional existing domain group in the same partner account.
            example:
              domain: acme-stories.example.com
              clientRef: ACME-1
              groupId: acme
      responses:
        '200':
          description: Existing domain attached or returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DomainRegistration'
        '201':
          description: Domain created; wait until active with trackingSyncPending false
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DomainRegistration'
        '400':
          description: Invalid request or configured domain limit reached
        '403':
          description: Partner access or required billing setup unavailable
        '404':
          description: Requested group not found
        '409':
          description: Domain conflict, paused site, or domain limit reached
        '429':
          description: Concurrent registration busy; retry with backoff and jitter
      security:
        - PartnerKeyAuth: []
components:
  schemas:
    DomainRegistration:
      type: object
      properties:
        success:
          type: boolean
        existing:
          type: boolean
        customerId:
          type: string
          description: >-
            Your shared partner account identifier, used by every site's
            returned snippet.
        domain:
          type: string
        clientRef:
          type: string
        groupId:
          type: string
        status:
          type: string
        pixelSnippet:
          type: string
          description: >-
            Install this in the site's shared page template. It contains no
            management or data API key.
        trackingSyncPending:
          type: boolean
          description: Tracking is ready when the domain is active and this is false.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'API key in format: mk_live_{40 hex chars}'
    PartnerKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        Partner management key (pk_live_...) from Partner Dashboard. Server-side
        use only; not a visitor-data key.

````

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