Traffic2Leads Partner API

Overview

The Partner API lets approved Traffic2Leads partners provision client accounts under their own management. One POST /v1/accounts call creates the client account, its lead campaign, and its tracking pixel — with a monthly lead cap you control and, optionally, a webhook that delivers every identified lead straight to your systems.

• Scoped to you. Your API key sees and manages only the accounts you created — nothing else.
• Setup, not lead routing. Leads flow directly from the Traffic2Leads platform to each account's configured delivery (your webhook, or the account portal). The Partner API is the control plane.
• Billed from creation. Every account goes live on billing immediately — there is no trial mode. A monthly_lead_cap is required on every account, so spend is always bounded.

Authentication

Every request (except /healthz) requires your partner API key as a Bearer token:

Authorization: Bearer t2l_pk_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Your key was issued to you by the Traffic2Leads team. Keep it server-side — never embed it in a browser or mobile app. If a key is compromised, contact us and we'll rotate it immediately.

Quickstart

Create a fully provisioned client account — pixel, caps, and webhook delivery — in one call:

curl -X POST https://partners.traffic2leads.ai/v1/accounts \
  -H "Authorization: Bearer t2l_pk_XXXX..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: acme-2026-08-07-001" \
  -d '{
    "client_name": "Acme Roofing",
    "client_email": "owner@acmeroofing.com",
    "account_type": "B2C",
    "monthly_lead_cap": 500,
    "webhook_url": "https://your-platform.com/hooks/t2l-leads"
  }'

const res = await fetch('https://partners.traffic2leads.ai/v1/accounts', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer t2l_pk_XXXX...',
    'Content-Type': 'application/json',
    'Idempotency-Key': 'acme-2026-08-07-001',
  },
  body: JSON.stringify({
    client_name: 'Acme Roofing',
    client_email: 'owner@acmeroofing.com',
    account_type: 'B2C',
    monthly_lead_cap: 500,
    webhook_url: 'https://your-platform.com/hooks/t2l-leads',
  }),
});
const account = await res.json();
// SAVE account.portal_password NOW — it is returned exactly once.

Then place the returned pixel_code (or javascript_code) on the client's website, and identified visitors start arriving at your webhook. That's the whole integration.

Create a client account

Creates the account, its lead campaign (active immediately), and its tracking pixel. Returns everything you need to onboard the client.

Request fields

Idempotency (recommended)

Send an Idempotency-Key header (any unique string, up to 128 chars) with every create. If your request times out and you retry with the same key within 24 hours, you get the original response back (marked with an Idempotency-Replayed: true header) instead of a second billed account.

Response 201

{
  "account_id": 42,
  "client_name": "SG — Acme Roofing",
  "client_email": "owner@acmeroofing.com",
  "account_type": "B2C",
  "caps": { "monthly_lead_cap": 500, "daily_cap": null, "cap_reset_day": null },
  "delivery_schedule": null,
  "state_filters": null,
  "zip_filters": null,
  "status": "active",
  "webhook_url": "https://your-platform.com/hooks/t2l-leads",
  "pixel_code": "<img src='https://rdcdn.com/rt?aid=XXXXX&e=1&img=1' ... />",
  "javascript_code": "<script> ... </script>",
  "portal_password": "Xu2!example",
  "created_at": "2026-08-07T18:31:02.558Z"
}

account_id is the ID you use on every other endpoint. Use pixel_code (image tag) or javascript_code (richer tracking) on the client's site — one of them, not both.

List your accounts

Returns every account you've created, newest first.

curl https://partners.traffic2leads.ai/v1/accounts \
  -H "Authorization: Bearer t2l_pk_XXXX..."

const res = await fetch('https://partners.traffic2leads.ai/v1/accounts', {
  headers: { 'Authorization': 'Bearer t2l_pk_XXXX...' },
});
const { accounts } = await res.json();

{
  "accounts": [
    {
      "account_id": 42,
      "client_name": "SG — Acme Roofing",
      "client_email": "owner@acmeroofing.com",
      "account_type": "B2C",
      "caps": { "monthly_lead_cap": 500, "daily_cap": null, "cap_reset_day": null },
      "delivery_schedule": null,
      "state_filters": null,
      "zip_filters": null,
      "status": "active",
      "webhook_url": "https://your-platform.com/hooks/t2l-leads",
      "created_at": "2026-08-07T18:31:02.558Z"
    }
  ]
}

Get one account

Same shape as the list entries, plus pixel_code and javascript_code so you can re-fetch the pixel any time. The portal_password is never included — it exists only in the create response.

Update account settings

Send any subset of the fields below — only what you send changes.

curl -X PATCH https://partners.traffic2leads.ai/v1/accounts/42 \
  -H "Authorization: Bearer t2l_pk_XXXX..." \
  -H "Content-Type: application/json" \
  -d '{ "monthly_lead_cap": 1000, "state_filters": ["TX", "OK"] }'

await fetch('https://partners.traffic2leads.ai/v1/accounts/42', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer t2l_pk_XXXX...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ monthly_lead_cap: 1000, state_filters: ['TX', 'OK'] }),
});

Responds 200 with the full updated account. PATCH /v1/accounts/{id}/limits also exists as a caps-only alias (accepts just the three cap fields).

Set or replace the delivery webhook

Point the account's lead delivery at a (new) HTTPS endpoint at any time.

curl -X PUT https://partners.traffic2leads.ai/v1/accounts/42/webhook \
  -H "Authorization: Bearer t2l_pk_XXXX..." \
  -H "Content-Type: application/json" \
  -d '{ "webhook_url": "https://your-platform.com/hooks/t2l-leads-v2" }'

await fetch('https://partners.traffic2leads.ai/v1/accounts/42/webhook', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer t2l_pk_XXXX...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ webhook_url: 'https://your-platform.com/hooks/t2l-leads-v2' }),
});

Pause / resume lead delivery

POST /v1/accounts/{id}/pause stops lead collection for the account; POST /v1/accounts/{id}/activate resumes it. Use pause when a client offboards — there is no delete (contact us for permanent removal).

Usage — lead counts

Per-account lead counts for billing and reporting. Two modes:

• ?month=YYYY-MM — a calendar month (defaults to the current month if omitted)
• ?start=YYYY-MM-DD&end=YYYY-MM-DD — any date range up to 366 days

curl "https://partners.traffic2leads.ai/v1/usage?start=2026-08-01&end=2026-08-31" \
  -H "Authorization: Bearer t2l_pk_XXXX..."

const res = await fetch(
  'https://partners.traffic2leads.ai/v1/usage?start=2026-08-01&end=2026-08-31',
  { headers: { 'Authorization': 'Bearer t2l_pk_XXXX...' } },
);
const usage = await res.json();

{
  "start": "2026-08-01",
  "end": "2026-08-31",
  "accounts": [
    { "account_id": 42, "client_name": "SG — Acme Roofing", "lead_count": 137 },
    { "account_id": 43, "client_name": "SG — Bright Dental", "lead_count": 88 }
  ],
  "total_leads": 225
}

Health check

No auth required. Returns {"status":"ok","db":"ok"} when the API is fully operational — useful for your monitoring.

Webhook lead payload

When an account has a webhook configured, each identified lead is delivered to your endpoint as an HTTP POST with a JSON body (Content-Type: application/json). Respond with a 2xx quickly; do your processing async. Fields:

Errors & rate limits

Rate limit: 60 requests per minute per API key. Exceeding it returns 429 with a Retry-After header (seconds). All errors share one shape:

{ "error": { "code": "validation_error", "message": "monthly_lead_cap: monthly_lead_cap is required" } }

Important notes

• Billing starts at creation. There is no trial mode. Caps are your spend control — monthly_lead_cap is required everywhere.
• Password resets are self-serve at login.traffic2leads.ai. Heads-up: the reset email arrives from a neutral platform domain (bit-sync.com), not a Traffic2Leads address.
• No lead history over the API. Leads are delivered to the account's webhook (and visible in the account portal). The API reports counts, not lead records — so make your webhook endpoint reliable, and use RecordId to de-duplicate.
• No delete endpoint. Pause an account to stop collection; contact us for permanent removal.
• Test with validate_only — it exercises your full request, including duplicate detection, without creating a billed account.

Questions or a stuck integration? Contact your Traffic2Leads account manager.