Tracking API
Track Click
Record an affiliate click event when a visitor lands via a referral link
POST /api/v1/track/click records an affiliate click event from the Affitor tracker script. It resolves the referral link from the ?aff= parameter (or its alias ?via=; aff wins when both are present), creates or reuses the customer record, and returns the click_id that downstream lead and sale calls will use for attribution.
This endpoint is called automatically by affitor-tracker.js. You only need to call it directly if you are building a custom tracker integration.
Auth
No API key is required. This endpoint is public — the referral link embedded in affiliate_url is the only credential needed.
Request
POST https://api.affitor.com/api/v1/track/click
Full URL including the ?aff= or ?via= query parameter, e.g. https://yoursite.com?aff=PARTNER123
Canonical page URL where the click occurred.
document.title at time of click.
document.referrer — where the visitor came from.
Browser session identifier.
User agent string; falls back to the HTTP User-Agent header.
Screen dimensions, e.g. 1920x1080.
Browser viewport dimensions, e.g. 1280x800.
Browser language code, e.g. en-US.
IANA timezone string, e.g. America/New_York.
The click_id stored for this visitor (the tracker sends it when the visitor comes back through another partner's link). A customer that already has this click ID is reused and keeps its first partner; the click is still recorded for the new partner. With program_id, a click ID whose customer belongs to another program is not reused, and the click gets a new click ID and customer. When no customer has the click ID, a new customer is created with it.
The program of the page (the tracker sends it). A numeric string such as "42" is accepted. When sent, the aff code is looked up only inside this program, and an id that is not a program returns 400 Unknown program_id. Without it, the lookup covers every program.
Your visitor's IP address, when your server records the click for that visitor. Used for the click's location only when the request carries the Bearer API key of the program the link belongs to (not a key past its rotation deadline) and the value is an IP address; otherwise the request's own IP is used. It never causes the click to be refused.
Pass {"test_mode": true, "program_id": 1} to create a test event that does not affect production attribution.
Example request body
curl -X POST https://api.affitor.com/api/v1/track/click \
-H "Content-Type: application/json" \
-d '{
"affiliate_url": "https://yoursite.com/pricing?aff=PARTNER123",
"page_url": "https://yoursite.com/pricing",
"page_title": "Pricing — YourSite",
"referrer_url": "https://blog.example.com/post",
"session_id": "sess_abc123",
"screen_resolution": "1920x1080",
"viewport_size": "1280x800",
"language": "en-US",
"timezone": "America/New_York"
}'Response
Success
{
"success": true,
"click_id": "cust_42_1715000000000",
"partner_code": "PARTNER123",
"cookie_window_days": 60
}| Field | Type | Description |
|---|---|---|
success | boolean | true on success |
click_id | string | Unique identifier for this click/customer relationship — store in a first-party cookie and pass to lead/sale calls |
partner_code | string | The short partner code resolved from the referral link |
cookie_window_days | number | Attribution window in days set by the program; click_id remains valid for this many days |
Test mode response
When additional_data.test_mode is true:
{
"success": true,
"message": "Test click event tracked successfully",
"data": {
"eventId": 101,
"programId": 1,
"test_mode": true
}
}Errors
| Status | Condition |
|---|---|
400 Bad Request | affiliate_url is missing |
400 Bad Request | affiliate_url cannot be parsed as a URL |
400 Bad Request | No ?aff= or ?via= parameter found in affiliate_url |
400 Bad Request | program_id was sent but is not a program (Unknown program_id) |
400 Bad Request | No referral link found matching the aff value |
400 Bad Request | Referral link configuration is invalid (missing partner or program) |
403 Forbidden | Test mode only: the Bearer key and additional_data.program_id name different programs (program_id does not match the API key) |
410 Gone | Referral link exists but is inactive. Body has error.code: link_disabled; no click is recorded |
500 Internal Server Error | Unexpected server error |
What happens on success
- The
affvalue is extracted fromaffiliate_urland matched to a referral link. - If
existing_click_idis provided and a customer already has that click ID, that customer is reused and keeps its first partner. The exception: whenprogram_idis sent and that customer belongs to another program, it is not reused and a new click ID is generated. When no customer is reused, a new customer record is created withcustomer_status: clickunder the returnedclick_id. - A click event is created in
affiliate_click_eventswith geo, device, and browser data derived server-side. - The referral link's
clickscounter andlast_clickedtimestamp are updated. - The partner-program click metrics are incremented.
click_id,partner_code, andcookie_window_daysare returned for the caller to store in a cookie.
Next steps
After a click is tracked:
- Lead Tracking — identify the customer when they sign up
- Payment Tracking — record a sale against the same customer
- Testing Integration — verify the full flow end-to-end