Track a visit — Rikochey

POST /api/websites/{website}/track

Records a page view and returns the visitor's fingerprint.

Check	Value
Authentication	none; the `Origin` is authoritative
Origin	checked against the website's host
Rate limiting	`api-track`, 60 per minute per IP

Body

Field	Type	Required	Purpose
`page_url`	URL, 2048 max	no	The page viewed; its campaign parameters are read from here
`page_title`	string, 255 max	no	Page title
`document_referrer`	string, 2048 max	no	`document.referrer`, from which the source is inferred
`forms_missing`	array, 20 max	no	Identifiers of forms expected on the page but not found

Example

curl -X POST https://api.example.com/api/websites/019f0000-0000-7000-8000-00000000000a/track \
  -H 'Content-Type: application/json' \
  -H 'Origin: https://www.example.com' \
  -d '{
        "page_url": "https://www.example.com/gates?utm_source=google&utm_campaign=spring",
        "page_title": "Swing gates",
        "document_referrer": "https://www.google.com/"
      }'

Response 200

{ "ok": true, "visitor_hash": "a509475fd53a7db2a5c049c576…" }

Keep visitor_hash and send it with the submission: it is what ties the request to the visit, and therefore to its source and campaign. The script stores it in window.VISITOR_HASH.

Errors

Code	Body	Cause
`403`	`{"error": "origin_not_allowed"}`	The `Origin` does not match the website's host
`404`	`{"message": "Website not found."}`	Unknown UUID
`422`	`{"message": "…", "errors": {…}}`	A field exceeds its length, or `page_url` is not a URL
`429`	—	More than 60 calls per minute from the same address

A tracking failure never breaks a page

Recording happens inside a protected block: if the write fails, the incident is logged server-side and the response is still 200, with the fingerprint. A page never stops working because tracking failed.

What is kept

The page viewed, the landing page, the source inferred from the referrer, the utm_* parameters and click identifiers (gclid, fbclid, msclkid…). The visitor fingerprint is recomputed server-side on every call: your value is only a hint, never an identity, and the IP address is not stored in clear.

Visit details are kept for thirteen months, then aggregated by day.

`forms_missing`

The script reports the forms it expected but could not find. The website then shows up in the client's integration report: this is how a page where the data-rikochey-form attribute was forgotten gets spotted. There is nothing for you to do with it — except add the missing attribute.