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. A browser lead that did not settle answers 200 with "provisional": true. 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.
The buyer's email address. Send it on every lead. When the lead settles, Affitor saves a one-way hash of it and a masked form (j***@example.com) on the customer, only if the customer has none yet; the lead never stores the address itself. It is the fallback that keeps a sale with the right partner: a Stripe Checkout payment that carries no click id (the buyer paid on another device or cleared their cookies) is matched to this customer by its checkout email, so it can still go to the partner who referred them. A provisional browser lead does not save it.
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