Track | Pieowl

Good to know

Send the pieowl-client-ip header with the visitor's IP address to get their location. Pieowl uses the IP only for the location lookup and the visitor hash. It does not store it.
Send the user-agent header with the visitor's user agent to get their device, browser and OS.

Authentication

Any client type works. From a server, send your client ID and client secret. See the Authentication guide.

bash

-H "pieowl-client-id: YOUR_CLIENT_ID" \
-H "pieowl-client-secret: YOUR_CLIENT_SECRET"

Base URL

plaintext

https://api.pieowl.com

Event types

Send a POST request to /track. The type field decides what gets recorded, and payload holds the data:

Type	What it does
`track`	Records a named event with optional properties
`identify`	Creates or updates a user profile
`increment`	Adds to a number property on a profile
`decrement`	Subtracts from a number property on a profile
`group`	Creates or updates a group
`assign_group`	Links a profile to one or more groups

Example: track an event

bash

curl -X POST 'https://api.pieowl.com/track' \
  -H 'Content-Type: application/json' \
  -H 'pieowl-client-id: YOUR_CLIENT_ID' \
  -H 'pieowl-client-secret: YOUR_CLIENT_SECRET' \
  -H 'pieowl-client-ip: 203.0.113.42' \
  -H 'user-agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)' \
  -d '{
    "type": "track",
    "payload": {
      "name": "signup",
      "properties": { "plan": "pro" },
      "profileId": "user_123"
    }
  }'

A successful request returns 200 with the deviceId and sessionId the event was linked to.

A purchase is a track event named revenue. __amount is in normal units, like 49.99. __currency is optional and defaults to your site currency. __orderId is your order number: the same order sent twice counts once. __deviceId is the visitor's device ID from pieowl.getDeviceId() in the browser, so the purchase is credited to their visit.

bash

curl -X POST 'https://api.pieowl.com/track' \
  -H 'Content-Type: application/json' \
  -H 'pieowl-client-id: YOUR_CLIENT_ID' \
  -H 'pieowl-client-secret: YOUR_CLIENT_SECRET' \
  -d '{
    "type": "track",
    "payload": {
      "name": "revenue",
      "properties": {
        "__amount": 49.99,
        "__currency": "EUR",
        "__orderId": "A-1001",
        "__deviceId": "DEVICE_ID"
      }
    }
  }'

For a refund, send the same event with "__refund": true and the __orderId. Leave out __amount to refund the whole order. See Revenue attribution.

Example: identify a user

bash

curl -X POST 'https://api.pieowl.com/track' \
  -H 'Content-Type: application/json' \
  -H 'pieowl-client-id: YOUR_CLIENT_ID' \
  -H 'pieowl-client-secret: YOUR_CLIENT_SECRET' \
  -d '{
    "type": "identify",
    "payload": {
      "profileId": "user_123",
      "email": "jane@example.com",
      "firstName": "Jane",
      "properties": { "company": "Example Inc" }
    }
  }'

Groups and events

Pieowl never adds groups to events on its own, not even after assign_group. Pass groups on each track call that needs group data.

For the full request and response schema of every event type, see the API Reference.