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.

Authentication

Mode	When to use	How
Server mode	Backend-driven signups	`Authorization: Bearer <program_api_token>`
Browser mode	Frontend signup flows, tracker already loaded	No `Authorization` header required — `click_id` proves attribution

In server mode, the Authorization header is optional but recommended. When present, Affitor validates the token against the program and cross-checks that the customer belongs to that program.

Request

Headers

AuthorizationheaderConditional

Bearer <program_api_token> — required for server mode, optional for browser mode.

Content-TypeheaderRequired

Must be application/json.

Body fields

click_idstringConditional

The affitor_click_id value from the affiliate click cookie. Required outside test mode unless customer_key is provided.

customer_keystringConditional

Your internal customer or user ID. Required outside test mode unless click_id is provided.

emailstringOptional

Customer email address. Used for hashed/masked attribution support.

additional_dataobjectOptional

Optional metadata. Supports test_mode (boolean), program_id (number), and event_name (string).

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 example

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"
}'

Response

Success — 200

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

Success — test mode (200)

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

Errors

Status	Condition
`400 Bad Request`	`click_id` and `customer_key` are both missing (outside test mode)
`400 Bad Request`	No customer record found for the provided `click_id` or `customer_key`
`400 Bad Request`	Customer does not belong to the authenticated program (server mode cross-program mismatch)
`400 Bad Request`	Customer status cannot transition to lead (e.g. already converted)
`401 Unauthorized`	`Authorization` header is present but the token is invalid or not found
`500 Internal Server Error`	Unexpected error during lead event creation

Test Mode

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

a real Bearer token is not required
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
  }
}

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

On this page