Track Click

POST /api/v1/track/click records an affiliate click event from the Affitor tracker script. It resolves the referral link from the ?aff= parameter, 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

affiliate_urlstringRequired

Full URL including the ?aff= query parameter, e.g. https://yoursite.com?aff=PARTNER123

page_urlstringOptional

Canonical page URL where the click occurred.

page_titlestringOptional

document.title at time of click.

referrer_urlstringOptional

document.referrer — where the visitor came from.

session_idstringOptional

Browser session identifier.

user_agentstringOptional

User agent string; falls back to the HTTP User-Agent header.

screen_resolutionstringOptional

Screen dimensions, e.g. 1920x1080.

viewport_sizestringOptional

Browser viewport dimensions, e.g. 1280x800.

languagestringOptional

Browser language code, e.g. en-US.

timezonestringOptional

IANA timezone string, e.g. America/New_York.

existing_click_idstringOptional

Previously issued click_id to reuse instead of generating a new one.

additional_dataobjectOptional

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=` parameter found in `affiliate_url`
`400 Bad Request`	No referral link found matching the `aff` value
`400 Bad Request`	Referral link configuration is invalid (missing partner or program)
`200` (with `success: false`)	Referral link exists but has `status: inactive`
`500 Internal Server Error`	Unexpected server error

What happens on success

The aff value is extracted from affiliate_url and matched to a referral link.
If existing_click_id is provided and matches an existing customer, that customer record is reused. Otherwise a new customer record is created with customer_status: click.
A click event is created in affiliate_click_events with geo, device, and browser data derived server-side.
The referral link's clicks counter and last_clicked timestamp are updated.
The partner-program click metrics are incremented.
click_id, partner_code, and cookie_window_days are 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

On this page