Partner API

Provision and manage end-customers entirely server-to-server. The Partner API is for resellers and platform integrators who want to embed Warm AI’s identification under their own brand — without sending their customers into the Warm AI dashboard.

When to use it

Use the Partner API when:

• You sell a product that bundles visitor identification (cold-email tools, sales-intel platforms, agency dashboards).
• Your customers should never log into a Warm AI URL — you control the UX end-to-end.
• You want per-customer quotas, billing, and reporting that you mirror into your own backend.

You don’t need the Partner API if you’re just identifying visitors on your own site — use the Identification API directly.

How the model works

┌──────────────────────────────────────────────────────────────┐
│  Partner account  (you)                                      │
│  ───────────────                                             │
│  • is_partner = true                                         │
│  • one master api_key   (the warm_… you authenticate with)   │
│                                                              │
│  ├── Child customer A    (parent_api_key_id = master)        │
│  │   • own api_key, own quota, own webhook                   │
│  │   • own tracking_script_id, own domain                    │
│  │                                                           │
│  ├── Child customer B                                        │
│  └── Child customer C                                        │
└──────────────────────────────────────────────────────────────┘

• Each child is a phantom user under your account. They have no login, no email inbox, no dashboard access. They exist purely as a billing + tracking unit you manage on their behalf.
• Each child has its own api_key (which you can hand back to the customer for server-side calls), its own tracking_script_id (for pulse.js install), its own subscription row (quota / period / topup balance), and its own optional webhook_url.
• All partner-* endpoints authenticate with your master x-access-key — never the child’s. The child’s key is for the child’s own tracker traffic.

Authentication

Every Partner API request must include:

The API rejects the call with 401 if the key is missing, unknown, or revoked, and 403 if the key is valid but is not the key designated as your partner master, or the account isn’t flagged is_partner=true.

Billing model

Each child has its own subscription row with:

The partner is invoiced for the IDs their children consume, aggregated across all customers, on whatever commercial agreement you have with us. You bill your end-customers however you like — the per-child id_price_pence_override is the unit cost you’ve agreed for that customer, so you can build margin into your own pricing.

How your own pool is billed

Above the per-child rows sits your pool. Every identification any of your children consumes draws from it. Which way you pay for that pool is set by pool_billing_mode, returned by partner-pool-state.

Both modes price at partner_per_id_pence, your agreed rate per identification. That rate is set by Warm as part of your commercial agreement and is not self-serve. Until it is set, top-ups are rejected, so if you are onboarding and partner-pool-state returns partner_per_id_pence: null, that is the thing to chase before anything else.

On prepaid you can have the pool refill itself: save a card, set a threshold and a reload amount, and we charge that card whenever available drops below the threshold. If auto-reload looks enabled but the pool is not refilling, check auto_reload.stripe_payment_method_id and auto_reload.consecutive_declines in the pool-state response before contacting support.

Endpoint surface

These endpoints cover the full customer lifecycle:

Plus the standard customer-facing endpoints, which you’ll call with the child’s api key (not yours) to fetch their visitors:

What’s not in the API yet

These pieces are planned and tracked on the roadmap. Until they ship, work around them as noted.

Next steps

• Quick Start — end-to-end TypeScript walkthrough: create a child, install the tracker, fetch visitors, release.
• Endpoints — full reference for every partner-* endpoint.
• Webhooks — real-time partner-side state-change events.