Tracking API

Base URL: /track

POST /track/init

Initialise or re-identify a visitor. Returns a unique visitor token that the frontend should persist (e.g. in localStorage) and send on every subsequent call.

Rate-limiting: If the same IP + User-Agent combination already created a token within the last 5 minutes, the existing token is returned instead of creating a new one.

Request

Field	Type	Required	Description
token	string	No	Previously issued visitor token (re-identify)
userAgent	string	No	Override User-Agent (falls back to request header)
utmSource	string	No	utm_source query param from landing URL
utmMedium	string	No	utm_medium query param
utmCampaign	string	No	utm_campaign query param
utmTerm	string	No	utm_term query param
utmContent	string	No	utm_content query param
referrer	string	No	document.referrer from the browser
landingUrl	string	No	Full landing page URL
invitedBy	string	No	User hashId or referral code of the referrer

IP is automatically read from x-forwarded-for header or socket. Geo (country, city, state) is resolved server-side from the IP at creation time.

Response 200 OK

{
  "token": "visitor_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "isNew": true
}

Field	Type	Description
token	string	Unique visitor token (persist on frontend)
isNew	boolean	true if a new visitor was created, false if existing

Behaviour

1. Token provided & valid → returns the same token, optionally fills in missing UTM/invitedBy fields.
2. No token / unknown token → computes fingerprint sha256(ip + userAgent):
   • If a visitor with matching fingerprint was created < 5 min ago → returns existing token (isNew: false).
   • Otherwise → creates a new visitor record with geo (country, city, state resolved from IP) and returns the fresh token (isNew: true).
3. Auth linking: When the user later logs in or registers, pass visitorToken in the POST /auth/verify or POST /auth/external/verify body. On first registration, the visitor record is linked to the new user — this records UTM, referrer, landing page, geo, and referral (invitedBy). The invitedById is also copied to the new User record.

Referral system

Pass invitedBy with either the referring user's hashId or their referral code. The server tries to resolve as a user hashId first, then falls back to looking up the referral code.

# Using referral code:
curl -X POST https://api.fonproxy.com/track/init \
  -H "Content-Type: application/json" \
  -d '{
    "invitedBy": "john_doe",
    "utmSource": "referral",
    "landingUrl": "https://fonproxy.com/?ref=john_doe"
  }'

# Using user hashId:
curl -X POST https://api.fonproxy.com/track/init \
  -H "Content-Type: application/json" \
  -d '{
    "invitedBy": "xK9mR2pL1w",
    "utmSource": "referral",
    "landingUrl": "https://fonproxy.com/?ref=xK9mR2pL1w"
  }'

When this visitor later registers, user.invitedBy (hashId) will be set in their profile.

Example

curl -X POST https://api.fonproxy.com/track/init \
  -H "Content-Type: application/json" \
  -d '{
    "utmSource": "google",
    "utmMedium": "cpc",
    "utmCampaign": "spring_sale",
    "referrer": "https://www.google.com/",
    "landingUrl": "https://fonproxy.com/?utm_source=google&utm_medium=cpc&utm_campaign=spring_sale"
  }'

---

Auth Integration

Both POST /auth/verify and POST /auth/external/verify now accept an optional visitorToken field in the request body. When a new user is created during login, the visitor record is automatically linked to that user.

{
  "email": "user@example.com",
  "code": "123456",
  "visitorToken": "visitor_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}