Siren

Report a Site Visit

POST /event/site-visited. Report a referred visit from your server, with credentials.

Requires Siren Pro

Last updated: October 26, 2026

POST /siren/v1/event/site-visited

Creates a Siren opportunity for a referred visitor and runs the standard engagement-trigger pipeline against it. Your server sends this with credentials: a WordPress application password for an administrator or Siren Platform Manager. A request without credentials is refused with 401. A visitor’s browser records a ?ref=… landing on /track/visit instead, with no credentials. Internally broadcasts a SiteVisited event, so engagement triggers and downstream listeners behave identically to a native WordPress visit.

Request Body:

FieldTypeRequiredDescription
collaboratorIdinteger or stringYesNumeric collaborator ID, or an alias reference in the form <type>:<code>. The most common alias form for tracking links is tracking:<referral-code> — the same code that appears in ?ref=… URLs. Resolved by the alias-resolver middleware before validation.
userIdintegerNoPlatform user ID to associate with the visit, if known. Only this route can tie a visit to a user.

Example Request:

POST /wp-json/siren/v1/event/site-visited
Authorization: Basic c2lyZW4tdHJhY2tpbmc6YWJjZCBlZmdoIGlqa2wgbW5vcA==
Content-Type: application/json

{
  "collaboratorId": "tracking:REF123"
}

Example Response:

HTTP/1.1 200 OK
X-Siren-OID: 4218
Access-Control-Expose-Headers: X-Siren-OID

The opportunity ID is in the X-Siren-OID response header. Persist it for the rest of the visitor’s session. The JSON body carries status, attributed, opportunityId, and message. status is attributed (the visit created or added to an engagement for the collaborator), recorded (the visit was recorded, and no active program of the collaborator rewards a visit), or not_attributed (nothing was written, and the body gives a reason).

To continue an existing opportunity instead of creating a new one, send the stored ID back in an X-Siren-OID request header on the call. Siren reads the header on the way in and uses it as the starting point for resolution.

For the full headless flow — persistence patterns, conversion-time round-trip, and recommendations on cookies vs local storage — see Headless Attribution.

Your privacy choices

Account, checkout and chat you request work without optional tracking. Choose whether to allow these other uses on this website.

You can change or withdraw your choices at any time using “Privacy choices.” We remember your choice for 180 days. Read our privacy policy.