Ingest events

curl --request POST \
  --url https://app.outlit.ai/api/i/v1/{publicKey}/events \
  --header 'Content-Type: application/json' \
  --data '
{
  "visitorId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "events": [
    {
      "type": "pageview",
      "timestamp": 123,
      "url": "<string>",
      "path": "<string>",
      "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "referrer": "<string>",
      "utm": {
        "source": "<string>",
        "medium": "<string>",
        "campaign": "<string>",
        "term": "<string>",
        "content": "<string>",
        "ref": "<string>"
      },
      "customerId": "<string>",
      "customerTraits": {},
      "title": "<string>"
    }
  ],
  "fingerprint": "<string>",
  "source": "client",
  "sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "userIdentity": {
    "email": "jsmith@example.com",
    "userId": "<string>",
    "fingerprint": "<string>",
    "traits": {}
  },
  "customerIdentity": {
    "customerId": "<string>",
    "customerTraits": {}
  }
}
'

import requests

url = "https://app.outlit.ai/api/i/v1/{publicKey}/events"

payload = {
    "visitorId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "events": [
        {
            "type": "pageview",
            "timestamp": 123,
            "url": "<string>",
            "path": "<string>",
            "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "referrer": "<string>",
            "utm": {
                "source": "<string>",
                "medium": "<string>",
                "campaign": "<string>",
                "term": "<string>",
                "content": "<string>",
                "ref": "<string>"
            },
            "customerId": "<string>",
            "customerTraits": {},
            "title": "<string>"
        }
    ],
    "fingerprint": "<string>",
    "source": "client",
    "sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "userIdentity": {
        "email": "jsmith@example.com",
        "userId": "<string>",
        "fingerprint": "<string>",
        "traits": {}
    },
    "customerIdentity": {
        "customerId": "<string>",
        "customerTraits": {}
    }
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    visitorId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    events: [
      {
        type: 'pageview',
        timestamp: 123,
        url: '<string>',
        path: '<string>',
        uuid: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
        referrer: '<string>',
        utm: {
          source: '<string>',
          medium: '<string>',
          campaign: '<string>',
          term: '<string>',
          content: '<string>',
          ref: '<string>'
        },
        customerId: '<string>',
        customerTraits: {},
        title: '<string>'
      }
    ],
    fingerprint: '<string>',
    source: 'client',
    sessionId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    userIdentity: {
      email: 'jsmith@example.com',
      userId: '<string>',
      fingerprint: '<string>',
      traits: {}
    },
    customerIdentity: {customerId: '<string>', customerTraits: {}}
  })
};

fetch('https://app.outlit.ai/api/i/v1/{publicKey}/events', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.outlit.ai/api/i/v1/{publicKey}/events",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'visitorId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'events' => [
        [
                'type' => 'pageview',
                'timestamp' => 123,
                'url' => '<string>',
                'path' => '<string>',
                'uuid' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
                'referrer' => '<string>',
                'utm' => [
                                'source' => '<string>',
                                'medium' => '<string>',
                                'campaign' => '<string>',
                                'term' => '<string>',
                                'content' => '<string>',
                                'ref' => '<string>'
                ],
                'customerId' => '<string>',
                'customerTraits' => [
                                
                ],
                'title' => '<string>'
        ]
    ],
    'fingerprint' => '<string>',
    'source' => 'client',
    'sessionId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'userIdentity' => [
        'email' => 'jsmith@example.com',
        'userId' => '<string>',
        'fingerprint' => '<string>',
        'traits' => [
                
        ]
    ],
    'customerIdentity' => [
        'customerId' => '<string>',
        'customerTraits' => [
                
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.outlit.ai/api/i/v1/{publicKey}/events"

	payload := strings.NewReader("{\n  \"visitorId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"events\": [\n    {\n      \"type\": \"pageview\",\n      \"timestamp\": 123,\n      \"url\": \"<string>\",\n      \"path\": \"<string>\",\n      \"uuid\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n      \"referrer\": \"<string>\",\n      \"utm\": {\n        \"source\": \"<string>\",\n        \"medium\": \"<string>\",\n        \"campaign\": \"<string>\",\n        \"term\": \"<string>\",\n        \"content\": \"<string>\",\n        \"ref\": \"<string>\"\n      },\n      \"customerId\": \"<string>\",\n      \"customerTraits\": {},\n      \"title\": \"<string>\"\n    }\n  ],\n  \"fingerprint\": \"<string>\",\n  \"source\": \"client\",\n  \"sessionId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"userIdentity\": {\n    \"email\": \"jsmith@example.com\",\n    \"userId\": \"<string>\",\n    \"fingerprint\": \"<string>\",\n    \"traits\": {}\n  },\n  \"customerIdentity\": {\n    \"customerId\": \"<string>\",\n    \"customerTraits\": {}\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.outlit.ai/api/i/v1/{publicKey}/events")
  .header("Content-Type", "application/json")
  .body("{\n  \"visitorId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"events\": [\n    {\n      \"type\": \"pageview\",\n      \"timestamp\": 123,\n      \"url\": \"<string>\",\n      \"path\": \"<string>\",\n      \"uuid\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n      \"referrer\": \"<string>\",\n      \"utm\": {\n        \"source\": \"<string>\",\n        \"medium\": \"<string>\",\n        \"campaign\": \"<string>\",\n        \"term\": \"<string>\",\n        \"content\": \"<string>\",\n        \"ref\": \"<string>\"\n      },\n      \"customerId\": \"<string>\",\n      \"customerTraits\": {},\n      \"title\": \"<string>\"\n    }\n  ],\n  \"fingerprint\": \"<string>\",\n  \"source\": \"client\",\n  \"sessionId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"userIdentity\": {\n    \"email\": \"jsmith@example.com\",\n    \"userId\": \"<string>\",\n    \"fingerprint\": \"<string>\",\n    \"traits\": {}\n  },\n  \"customerIdentity\": {\n    \"customerId\": \"<string>\",\n    \"customerTraits\": {}\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.outlit.ai/api/i/v1/{publicKey}/events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"visitorId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"events\": [\n    {\n      \"type\": \"pageview\",\n      \"timestamp\": 123,\n      \"url\": \"<string>\",\n      \"path\": \"<string>\",\n      \"uuid\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n      \"referrer\": \"<string>\",\n      \"utm\": {\n        \"source\": \"<string>\",\n        \"medium\": \"<string>\",\n        \"campaign\": \"<string>\",\n        \"term\": \"<string>\",\n        \"content\": \"<string>\",\n        \"ref\": \"<string>\"\n      },\n      \"customerId\": \"<string>\",\n      \"customerTraits\": {},\n      \"title\": \"<string>\"\n    }\n  ],\n  \"fingerprint\": \"<string>\",\n  \"source\": \"client\",\n  \"sessionId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"userIdentity\": {\n    \"email\": \"jsmith@example.com\",\n    \"userId\": \"<string>\",\n    \"fingerprint\": \"<string>\",\n    \"traits\": {}\n  },\n  \"customerIdentity\": {\n    \"customerId\": \"<string>\",\n    \"customerTraits\": {}\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "processed": 4503599627370495,
  "errors": [
    {
      "index": 0,
      "message": "<string>"
    }
  ]
}

{
  "success": true,
  "processed": 4503599627370495,
  "errors": [
    {
      "index": 0,
      "message": "<string>"
    }
  ]
}

{
  "success": true,
  "processed": 4503599627370495,
  "errors": [
    {
      "index": 0,
      "message": "<string>"
    }
  ]
}

{
  "success": true,
  "processed": 4503599627370495,
  "errors": [
    {
      "index": 0,
      "message": "<string>"
    }
  ]
}

POST

api

{publicKey}

events

Ingest events

curl --request POST \
  --url https://app.outlit.ai/api/i/v1/{publicKey}/events \
  --header 'Content-Type: application/json' \
  --data '
{
  "visitorId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "events": [
    {
      "type": "pageview",
      "timestamp": 123,
      "url": "<string>",
      "path": "<string>",
      "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "referrer": "<string>",
      "utm": {
        "source": "<string>",
        "medium": "<string>",
        "campaign": "<string>",
        "term": "<string>",
        "content": "<string>",
        "ref": "<string>"
      },
      "customerId": "<string>",
      "customerTraits": {},
      "title": "<string>"
    }
  ],
  "fingerprint": "<string>",
  "source": "client",
  "sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "userIdentity": {
    "email": "jsmith@example.com",
    "userId": "<string>",
    "fingerprint": "<string>",
    "traits": {}
  },
  "customerIdentity": {
    "customerId": "<string>",
    "customerTraits": {}
  }
}
'

import requests

url = "https://app.outlit.ai/api/i/v1/{publicKey}/events"

payload = {
    "visitorId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "events": [
        {
            "type": "pageview",
            "timestamp": 123,
            "url": "<string>",
            "path": "<string>",
            "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "referrer": "<string>",
            "utm": {
                "source": "<string>",
                "medium": "<string>",
                "campaign": "<string>",
                "term": "<string>",
                "content": "<string>",
                "ref": "<string>"
            },
            "customerId": "<string>",
            "customerTraits": {},
            "title": "<string>"
        }
    ],
    "fingerprint": "<string>",
    "source": "client",
    "sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "userIdentity": {
        "email": "jsmith@example.com",
        "userId": "<string>",
        "fingerprint": "<string>",
        "traits": {}
    },
    "customerIdentity": {
        "customerId": "<string>",
        "customerTraits": {}
    }
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    visitorId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    events: [
      {
        type: 'pageview',
        timestamp: 123,
        url: '<string>',
        path: '<string>',
        uuid: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
        referrer: '<string>',
        utm: {
          source: '<string>',
          medium: '<string>',
          campaign: '<string>',
          term: '<string>',
          content: '<string>',
          ref: '<string>'
        },
        customerId: '<string>',
        customerTraits: {},
        title: '<string>'
      }
    ],
    fingerprint: '<string>',
    source: 'client',
    sessionId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    userIdentity: {
      email: 'jsmith@example.com',
      userId: '<string>',
      fingerprint: '<string>',
      traits: {}
    },
    customerIdentity: {customerId: '<string>', customerTraits: {}}
  })
};

fetch('https://app.outlit.ai/api/i/v1/{publicKey}/events', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.outlit.ai/api/i/v1/{publicKey}/events",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'visitorId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'events' => [
        [
                'type' => 'pageview',
                'timestamp' => 123,
                'url' => '<string>',
                'path' => '<string>',
                'uuid' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
                'referrer' => '<string>',
                'utm' => [
                                'source' => '<string>',
                                'medium' => '<string>',
                                'campaign' => '<string>',
                                'term' => '<string>',
                                'content' => '<string>',
                                'ref' => '<string>'
                ],
                'customerId' => '<string>',
                'customerTraits' => [
                                
                ],
                'title' => '<string>'
        ]
    ],
    'fingerprint' => '<string>',
    'source' => 'client',
    'sessionId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'userIdentity' => [
        'email' => 'jsmith@example.com',
        'userId' => '<string>',
        'fingerprint' => '<string>',
        'traits' => [
                
        ]
    ],
    'customerIdentity' => [
        'customerId' => '<string>',
        'customerTraits' => [
                
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.outlit.ai/api/i/v1/{publicKey}/events"

	payload := strings.NewReader("{\n  \"visitorId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"events\": [\n    {\n      \"type\": \"pageview\",\n      \"timestamp\": 123,\n      \"url\": \"<string>\",\n      \"path\": \"<string>\",\n      \"uuid\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n      \"referrer\": \"<string>\",\n      \"utm\": {\n        \"source\": \"<string>\",\n        \"medium\": \"<string>\",\n        \"campaign\": \"<string>\",\n        \"term\": \"<string>\",\n        \"content\": \"<string>\",\n        \"ref\": \"<string>\"\n      },\n      \"customerId\": \"<string>\",\n      \"customerTraits\": {},\n      \"title\": \"<string>\"\n    }\n  ],\n  \"fingerprint\": \"<string>\",\n  \"source\": \"client\",\n  \"sessionId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"userIdentity\": {\n    \"email\": \"jsmith@example.com\",\n    \"userId\": \"<string>\",\n    \"fingerprint\": \"<string>\",\n    \"traits\": {}\n  },\n  \"customerIdentity\": {\n    \"customerId\": \"<string>\",\n    \"customerTraits\": {}\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.outlit.ai/api/i/v1/{publicKey}/events")
  .header("Content-Type", "application/json")
  .body("{\n  \"visitorId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"events\": [\n    {\n      \"type\": \"pageview\",\n      \"timestamp\": 123,\n      \"url\": \"<string>\",\n      \"path\": \"<string>\",\n      \"uuid\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n      \"referrer\": \"<string>\",\n      \"utm\": {\n        \"source\": \"<string>\",\n        \"medium\": \"<string>\",\n        \"campaign\": \"<string>\",\n        \"term\": \"<string>\",\n        \"content\": \"<string>\",\n        \"ref\": \"<string>\"\n      },\n      \"customerId\": \"<string>\",\n      \"customerTraits\": {},\n      \"title\": \"<string>\"\n    }\n  ],\n  \"fingerprint\": \"<string>\",\n  \"source\": \"client\",\n  \"sessionId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"userIdentity\": {\n    \"email\": \"jsmith@example.com\",\n    \"userId\": \"<string>\",\n    \"fingerprint\": \"<string>\",\n    \"traits\": {}\n  },\n  \"customerIdentity\": {\n    \"customerId\": \"<string>\",\n    \"customerTraits\": {}\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.outlit.ai/api/i/v1/{publicKey}/events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"visitorId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"events\": [\n    {\n      \"type\": \"pageview\",\n      \"timestamp\": 123,\n      \"url\": \"<string>\",\n      \"path\": \"<string>\",\n      \"uuid\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n      \"referrer\": \"<string>\",\n      \"utm\": {\n        \"source\": \"<string>\",\n        \"medium\": \"<string>\",\n        \"campaign\": \"<string>\",\n        \"term\": \"<string>\",\n        \"content\": \"<string>\",\n        \"ref\": \"<string>\"\n      },\n      \"customerId\": \"<string>\",\n      \"customerTraits\": {},\n      \"title\": \"<string>\"\n    }\n  ],\n  \"fingerprint\": \"<string>\",\n  \"source\": \"client\",\n  \"sessionId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"userIdentity\": {\n    \"email\": \"jsmith@example.com\",\n    \"userId\": \"<string>\",\n    \"fingerprint\": \"<string>\",\n    \"traits\": {}\n  },\n  \"customerIdentity\": {\n    \"customerId\": \"<string>\",\n    \"customerTraits\": {}\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "processed": 4503599627370495,
  "errors": [
    {
      "index": 0,
      "message": "<string>"
    }
  ]
}

{
  "success": true,
  "processed": 4503599627370495,
  "errors": [
    {
      "index": 0,
      "message": "<string>"
    }
  ]
}

{
  "success": true,
  "processed": 4503599627370495,
  "errors": [
    {
      "index": 0,
      "message": "<string>"
    }
  ]
}

{
  "success": true,
  "processed": 4503599627370495,
  "errors": [
    {
      "index": 0,
      "message": "<string>"
    }
  ]
}

Use your organization’s pk_ public key in the URL path. Ingest requests do not use a bearer API key.

Request body

{
  "visitorId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "source": "client",
  "events": [
    {
      "type": "pageview",
      "url": "https://example.com/pricing",
      "path": "/pricing",
      "title": "Pricing - Example",
      "referrer": "https://google.com",
      "timestamp": 1699999999999
    }
  ]
}

For browser (client) tracking, send a UUID visitorId; server events can omit it when an event provides email, userId, fingerprint, or customerId for identity or account attribution. source defaults to client and also accepts server or integration. Send 1–100 events per request. When a browser user is logged in, userIdentity can provide email, a system-owned userId, and user traits for immediate resolution. customerIdentity can provide a system-owned customerId and customerTraits for account attribution across the whole batch.

Event types

All events share these common fields:

Field	Type	Required	Description
`type`	string	Yes	Event type (see below)
`timestamp`	number	No	Unix timestamp in milliseconds. Defaults to server time.
`url`	string	Yes	Full page URL
`path`	string	Yes	URL path (e.g., `/pricing`)
`referrer`	string	No	Referrer URL
`utm`	object	No	UTM parameters (see below)

UTM parameters

{
  "utm": {
    "source": "google",
    "medium": "cpc",
    "campaign": "spring_2024",
    "term": "pricing software",
    "content": "header_cta"
  }
}

Pageview event

Track a page view.

{
  "type": "pageview",
  "url": "https://example.com/pricing?plan=pro",
  "path": "/pricing",
  "title": "Pricing - Example",
  "referrer": "https://google.com/search?q=example",
  "utm": {
    "source": "google",
    "medium": "cpc",
    "campaign": "spring_2024"
  },
  "timestamp": 1699999999999
}

Set type to pageview. title is the page title when available.

Custom event

Track any custom event.

{
  "type": "custom",
  "url": "https://example.com/pricing",
  "path": "/pricing",
  "eventName": "button_clicked",
  "properties": {
    "buttonId": "cta-hero",
    "page": "/pricing",
    "variant": "A"
  },
  "timestamp": 1699999999999
}

Set type to custom and provide an eventName. The optional properties map accepts string, number, boolean, and null values.

Form event

Track a form submission.

{
  "type": "form",
  "url": "https://example.com/contact",
  "path": "/contact",
  "formId": "contact-form",
  "formFields": {
    "email": "jane@example.com",
    "name": "Jane Doe",
    "company": "Acme Inc",
    "message": "I'd like to learn more..."
  },
  "timestamp": 1699999999999
}

Set type to form. formId is the form’s ID or name; formFields holds field names and values.

Do not send passwords, payment details, or national identifiers. Outlit filters formFields using a field denylist and sensitive-value checks; these safeguards do not replace filtering at the source.

Identify event

Identify the visitor with their email/userId.

{
  "type": "identify",
  "url": "https://example.com/signup",
  "path": "/signup",
  "email": "jane@example.com",
  "userId": "usr_12345",
  "customerId": "cust_123",
  "traits": {
    "name": "Jane Doe",
    "company": "Acme Inc",
    "plan": "enterprise",
    "role": "admin"
  },
  "customerTraits": {
    "plan": "enterprise",
    "seats": 50
  },
  "timestamp": 1699999999999
}

Set type to identify and provide at least one of email or your system-owned userId. traits updates the user profile. Send your system-owned customerId to link that external account or workspace to the resolved contact; customerTraits updates its profile.

Engagement event

Track active time on a page. Automatically sent by the Outlit Browser SDK.

{
  "type": "engagement",
  "url": "https://example.com/features",
  "path": "/features",
  "activeTimeMs": 45000,
  "totalTimeMs": 60000,
  "sessionId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "timestamp": 1699999999999
}

Set type to engagement. Send activeTimeMs for visible-tab interaction time and totalTimeMs for total wall-clock time on the page. sessionId is a UUID that groups engagement events and resets after 30 minutes of inactivity or when the tab closes.

Calendar event

Track calendar booking from embedded widgets (Cal.com, Calendly).

{
  "type": "calendar",
  "url": "https://example.com/demo",
  "path": "/demo",
  "provider": "cal.com",
  "eventType": "30 Minute Demo",
  "startTime": "2024-03-15T10:00:00Z",
  "endTime": "2024-03-15T10:30:00Z",
  "duration": 30,
  "isRecurring": false,
  "timestamp": 1699999999999
}

Set type to calendar and provider to cal.com, calendly, or unknown. eventType names the meeting; startTime and endTime use ISO 8601, duration is in minutes, and isRecurring indicates a recurring meeting. inviteeEmail and inviteeName are available only through server-side webhooks.

Response

Success response

{
  "success": true,
  "processed": 3
}

processed counts the successfully processed events. Inspect errors when success is false.

Partial success response (HTTP 207)

When some events succeed and others fail:

{
  "success": false,
  "processed": 2,
  "errors": [
    {
      "index": 2,
      "message": "Invalid event type"
    }
  ]
}

Error response

{
  "success": false,
  "processed": 0,
  "errors": [
    {
      "index": -1,
      "message": "Invalid or inactive tracking configuration"
    }
  ]
}

Examples

cURL - browser events

curl -X POST "https://app.outlit.ai/api/i/v1/pk_your_key/events" \
  -H "Content-Type: application/json" \
  -d '{
    "visitorId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "source": "client",
    "events": [
      {
        "type": "pageview",
        "url": "https://example.com/pricing",
        "path": "/pricing",
        "title": "Pricing",
        "timestamp": 1699999999999
      }
    ]
  }'

cURL - server events

curl -X POST "https://app.outlit.ai/api/i/v1/pk_your_key/events" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "server",
    "events": [
      {
        "type": "identify",
        "url": "server://jane@acme.com",
        "path": "/",
        "email": "jane@acme.com",
        "userId": "usr_123",
        "customerId": "cust_123",
        "traits": {
          "name": "Jane Doe",
          "plan": "pro"
        },
        "customerTraits": {
          "plan": "pro"
        }
      },
      {
        "type": "custom",
        "url": "server://jane@acme.com",
        "path": "/",
        "eventName": "subscription_created",
        "email": "jane@acme.com",
        "userId": "usr_123",
        "customerId": "cust_123",
        "properties": {
          "plan": "pro",
          "amount": 99
        }
      }
    ]
  }'

JavaScript (fetch)

const response = await fetch(
  'https://app.outlit.ai/api/i/v1/pk_your_key/events',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      visitorId: 'visitor-123',
      source: 'client',
      events: [
        {
          type: 'pageview',
          url: window.location.href,
          path: window.location.pathname,
          title: document.title,
          timestamp: Date.now()
        }
      ]
    })
  }
)

const result = await response.json()
console.log(result)

Python

import requests
import time

response = requests.post(
    'https://app.outlit.ai/api/i/v1/pk_your_key/events',
    json={
        'source': 'server',
        'events': [
            {
                'type': 'identify',
                'url': 'server://jane@example.com',
                'path': '/',
                'email': 'jane@example.com',
                'customerId': 'cust_123',
                'traits': {'name': 'Jane Doe'},
                'customerTraits': {'plan': 'enterprise'},
                'timestamp': int(time.time() * 1000)
            }
        ]
    }
)

print(response.json())

Server-side events

For server-side tracking, the visitorId field can be omitted. Identity is resolved from the event data, including customer-only attribution when customerId is provided:

Identify events: Use email and/or userId fields, plus optional customer context
Custom events: Include top-level email, userId, fingerprint, and/or customerId fields

{
  "source": "server",
  "events": [
    {
      "type": "custom",
      "url": "server://user@example.com",
      "path": "/",
      "eventName": "payment_received",
      "email": "user@example.com",
      "userId": "usr_123",
      "customerId": "cust_123",
      "properties": {
        "amount": 99,
        "currency": "USD"
      }
    }
  ]
}

Server events require identity or account attribution. Custom events need at least one of email, userId, fingerprint, or customerId; identify events need email or userId.

Batching best practices

For high-volume tracking:

Batch events - Send multiple events per request (up to 100)
Use background queue - Don’t block user actions
Retry with backoff - Handle temporary failures
Flush on shutdown - Send remaining events before exit

// Example batching implementation
const eventQueue = []
const FLUSH_INTERVAL = 5000
const MAX_BATCH_SIZE = 100

function track(event) {
  eventQueue.push({ ...event, timestamp: Date.now() })
  
  if (eventQueue.length >= MAX_BATCH_SIZE) {
    flush()
  }
}

async function flush() {
  if (eventQueue.length === 0) return
  
  const events = eventQueue.splice(0, MAX_BATCH_SIZE)
  
  try {
    await fetch('/api/i/v1/pk_xxx/events', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        visitorId: getVisitorId(),
        source: 'client',
        events
      })
    })
  } catch (error) {
    // Re-queue failed events
    eventQueue.unshift(...events)
  }
}

setInterval(flush, FLUSH_INTERVAL)
window.addEventListener('beforeunload', flush)

Path Parameters

publicKey

string

required

Minimum string length: 1

Body

application/json

Option 1
Option 2

visitorId

string<uuid>

required

Pattern:

^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

events

required

Required array length: 1 - 100 elements

Show child attributes

fingerprint

string

Minimum string length: 1

source

enum<string>

default:client

Available options:

client,

server,

integration

sessionId

string<uuid>

Pattern:

^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

userIdentity

object

Show child attributes

customerIdentity

object

Show child attributes

Response

Ingestion result

success

boolean

required

processed

integer

required

Required range: 0 <= x <= 9007199254740991

errors

object[]

Show child attributes

Overview

Platform API

Ingest API

Ingest events

Request body

Event types

UTM parameters

Pageview event

Custom event

Form event

Identify event

Engagement event

Calendar event

Response

Success response

Partial success response (HTTP 207)

Error response

Examples

cURL - browser events

cURL - server events

JavaScript (fetch)

Python

Server-side events

Batching best practices

Path Parameters

Body

Response

​Request body

​Event types

​UTM parameters

​Pageview event

​Custom event

​Form event

​Identify event

​Engagement event

​Calendar event

​Response

​Success response

​Partial success response (HTTP 207)

​Error response

​Examples

​cURL - browser events

​cURL - server events

​JavaScript (fetch)

​Python

​Server-side events

​Batching best practices

Path Parameters

Body

Response

Request body

Event types

UTM parameters

Pageview event

Custom event

Form event

Identify event

Engagement event

Calendar event

Response

Success response

Partial success response (HTTP 207)

Error response

Examples

cURL - browser events

cURL - server events

JavaScript (fetch)

Python

Server-side events

Batching best practices