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