API Keys

An API key lets a partner's dashboard, or your own scripts, read your Lead Tracking data through the Tag Pilot API. Keys are read-only and can be limited to specific projects.

Create a key

1. In the Tag Pilot app, open Settings → API keys and click New key. You can also start from a project's Setup tab → API access → New key for this project.
2. Give it a label, for example the partner's name, so you know which key is whose.
3. Choose All projects (including ones added later) or tick the projects the key may read.
4. Copy the key. It starts with tpk_ and is shown only once.

Create one key per partner, so you can revoke each on its own. The list shows when each key was last used.

Use a key

Send the key in the Authorization header of every request, and set your own User-Agent:

curl -H "Authorization: Bearer tpk_your_key_here" \
  -H "User-Agent: acme-dashboard/1.0" \
  https://api.tagpilot.io/integrations/v1/lead-tracking/projects

The response lists the projects the key can read, with their IDs:

{
  "items": [
    {
      "id": "1f1c630c-45aa-6f10-9752-8f89d42c1d24",
      "name": "example.com",
      "retention_days": 365,
      "status_events": { "Suspect": "qualify_lead", "Client": "close_convert_lead" },
      "created_at": "2026-10-12T11:33:37Z"
    }
  ]
}

GET /integrations/v1/lead-tracking/projects/{projectId} returns one project, plus status_counts: the number of leads per CRM status ("" = no status yet).

Keep keys safe

• Server to server only. Never put a key in browser code, a mobile app or a public repository.
• Set a User-Agent. Our firewall blocks some default client user agents (for example Python's urllib), which shows up as a Cloudflare error page.
• Revoke a key under Settings → API keys as soon as it is no longer needed or may have leaked; it stops working immediately.
• A key can never read more than its creator can: if you lose access to a shared project, your keys lose it too.

What the API shares

Masked email addresses (j****e@g***l.com), CRM statuses and their dates, values, and lead sources: UTM parameters, which ad click ID types were present (gclid, fbclid, …), the referrer's host and landing pages without their query string.

It never returns full or hashed email addresses, click ID values, cookies, IP addresses, browser details, consent signals or your CRM's raw data.

Errors

Errors return JSON such as {"code": 401, "message": "Invalid or revoked API key."}.