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:
| 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. 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.