Report a Site Visit

POST /siren/v1/event/site-visited

Creates a Siren opportunity for a referred visitor and runs the standard engagement-trigger pipeline against it. Used by headless frontends to report a ?ref=… landing the way a WordPress page render would automatically. Internally broadcasts a SiteVisited event, so engagement triggers and downstream listeners behave identically to a native WordPress visit.

Request Body:

Field	Type	Required	Description
collaboratorId	integer or string	Yes	Numeric 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.
userId	integer	No	Platform user ID to associate with the visit, if known.

Example Request:

POST /wp-json/siren/v1/event/site-visited
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 body is empty. The opportunity ID is in the X-Siren-OID response header — read it client-side and persist it for the rest of the visitor’s session.

To continue an existing opportunity instead of creating a new one, send the existing ID 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.