Tracking API
Track Lead
Record a signup or lead event that links a customer to an affiliate click.
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 (recommended) | Your backend calls the API after a signup | Authorization: Bearer <program_api_token> |
| Browser mode | The tracker's signup() call from the page | No Authorization header — the call carries only the click_id |
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 policy
Each program has a lead auth policy. Every program requires server-verified leads (server_required) unless it is explicitly set to allow browser leads (browser_allowed). Under server_required, a browser-mode lead is recorded as provisional:
- the API still returns
200, withprovisional: truein the body - the lead does not settle attribution, does not save your
customer_keyon 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/saledoes not settle it, and a Bearer lead sent after that sale returns400
A browser lead settles directly only on a program set to browser_allowed. The Lead capture mode line in your program's tracking settings shows which policy applies. Send leads from your server with a Bearer key so the lead settles under either policy.
Request
Headers
Bearer <program_api_token> — send it for server mode. Without it, the call is treated as browser mode.
Must be application/json.
Body fields
The affitor_click_id value from the affiliate click cookie. Send it on every lead outside test mode: Affitor finds the customer through the click.
Your internal customer or user ID. Send it with the click_id: when the lead settles, Affitor saves it on that customer, so later sales can find the customer by your own id. On its own it finds no customer on a first lead, because the key is saved only when a lead settles.
Customer email address. Used for hashed/masked attribution support.
Optional metadata. Supports test_mode (boolean), program_id (number), and event_name (string).
The program of the page (the tracker sends it). Read only in browser mode; with a Bearer key, the key's program decides. When sent, the customer found by click_id or customer_key must belong to this program; otherwise the lead answers 400 Customer not found. Provide a valid click_id or customer_key.
Outside test mode, send the click_id with your customer_key. A request with neither answers 400 click_id or customer_key is required. A first lead with only customer_key answers 400 Customer not found. Provide a valid click_id or customer_key., because Affitor saves your key on the customer only when a lead settles. Without a Bearer key, click_id is always required.
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 — provisional browser lead (200)
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)
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): click_id or customer_key is required |
400 Bad Request | Browser mode: customer_key was sent without click_id (click_id is required when no API key is sent) |
400 Bad Request | No customer record found for the provided click_id or customer_key (for example a first lead sent with only customer_key), or (browser mode) the customer does not belong to the program_id sent |
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 |
403 Forbidden | Test mode only: the Bearer key and additional_data.program_id name different programs (program_id does not match the API key) |
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 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_idto 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
}
}Related
- Click Tracking — must run before lead tracking
- Lead Tracking Guide — implementation examples (Node.js, Python, browser)
- Track Sale — next step after a successful lead