Record a Referred Visit

POST /siren/v1/track/visit

Records a referred visit from a visitor’s browser. A headless frontend calls it when a visitor lands with ?ref=…, the way a WordPress page render records the visit on its own. The route takes no credentials. It runs the same pipeline as /event/site-visited and records nothing else. This route is on WordPress only. On Siren Cloud, a Stripe or Shopify site records visits with its tracking line, and a WordPress site records them through the Siren Cloud Connector.

Every visit on this route is anonymous. Siren ignores a userId in the body, so a browser can’t tie a visit to a WordPress user. To tie a visit to a user, send it from your server to /event/site-visited with credentials.

Request Body:

Field	Type	Required	Description
collaboratorId	integer or string	Yes	Numeric collaborator ID, or an alias reference in the form <type>:<code>. Tracking links use tracking:<referral-code>, the same code that appears in ?ref=… URLs.

Example Request:

POST /wp-json/siren/v1/track/visit
Content-Type: application/json
X-Siren-OID: 4218

{
  "collaboratorId": "tracking:REF123"
}

Leave out X-Siren-OID on a visitor’s first visit.

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. Store it in a first-party cookie or local storage, send it back in X-Siren-OID on the visitor’s next visit to continue the same opportunity, and send it on the conversion call.

A Siren version older than this route answers 404. A frontend that has to work before and after the plugin upgrade can send the visit to /event/site-visited once when that happens. Siren versions with this route refuse an anonymous /event/site-visited with 401.

For the full headless flow, see Headless Attribution.