Track Lead

POST /api/v1/track/lead

Records a lead event for a customer who signed up through an affiliate referral. Call this after a successful registration so Affitor can advance the attribution chain from click → lead.

AuthenticationCopy Anchor Link

The mode is decided by the header: a request with a valid Bearer key is server mode, and a request without one is browser mode. In server mode, Affitor validates the key and checks that the customer belongs to that program.

Lead auth policyCopy Anchor Link

Each program has a lead auth policy. New programs default to server-verified leads (server_required). Under that policy, a browser-mode lead is recorded as provisional:

• the API still returns 200, with provisional: true in the body
• the lead does not settle attribution, does not save your customer_key on the customer, and does not count in partner metrics or pay a per-lead commission
• it settles only when your backend sends the same lead with a Bearer key, or when a Stripe Checkout payment for that customer arrives through your connected Stripe account. A sale sent to /api/v1/track/sale does not settle it, and a Bearer lead sent after that sale returns 400

Programs created before this policy existed keep the older behavior, where a browser lead settles directly. Send leads from your server with a Bearer key so the lead settles under either policy.

RequestCopy Anchor Link

HeadersCopy Anchor Link

Body fieldsCopy Anchor Link

Outside test mode, at least one of click_id or customer_key must be provided. Providing both is recommended for reliable downstream payment attribution.

Request body exampleCopy Anchor Link

curl -X POST https://api.affitor.com/api/v1/track/lead \
-H "Authorization: Bearer YOUR_PROGRAM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "click_id": "cust_42_1234567890",
  "customer_key": "usr_abc123",
  "email": "user@example.com"
}'

ResponseCopy Anchor Link

Success — 200Copy Anchor Link

{
  "success": true,
  "message": "Lead tracked successfully"
}

Success — provisional browser lead (200)Copy Anchor Link

Returned for a browser-mode lead (no Bearer key) when the program requires server-verified leads. The lead is stored but not settled; see Lead auth policy.

{
  "success": true,
  "provisional": true,
  "message": "Lead recorded as provisional. This program requires server-side (Bearer) lead tracking to settle attribution."
}

Success — test mode (200)Copy Anchor Link

When additional_data.test_mode is true, the response includes the created event details:

{
  "success": true,
  "message": "Test lead event tracked successfully",
  "data": {
    "eventId": 456,
    "programId": 1,
    "test_mode": true
  }
}

ErrorsCopy Anchor Link

Test ModeCopy Anchor Link

Send additional_data.test_mode: true to create a test lead event without affecting production attribution. In test mode:

• a Bearer key is not required to store the test event, but only a test event sent with your program API key counts toward integration verification
• pass additional_data.program_id to associate the test event with a specific program
• the event is created with is_test: true

{
  "click_id": "test_lead_001",
  "customer_key": "test_customer",
  "additional_data": {
    "test_mode": true,
    "program_id": 1
  }
}

RelatedCopy Anchor Link

• Click Tracking — must run before lead tracking
• Lead Tracking Guide — implementation examples (Node.js, Python, browser)
• Track Sale — next step after a successful lead