Ingest Events

Send tracking events to Outlit

POST /api/i/v1/{publicKey}/events

Ingest Events

cURL

curl --request POST \
  --url https://api.example.com/api/i/v1/{publicKey}/events \
  --header 'Content-Type: application/json' \
  --data '
{
  "visitorId": "<string>",
  "source": "<string>",
  "events": [
    {}
  ],
  "userIdentity": {},
  "customerIdentity": {},
  "type": "<string>",
  "title": "<string>",
  "eventName": "<string>",
  "properties": {},
  "formId": "<string>",
  "formFields": {},
  "email": "<string>",
  "userId": "<string>",
  "traits": {},
  "customerId": "<string>",
  "customerTraits": {},
  "activeTimeMs": 123,
  "totalTimeMs": 123,
  "sessionId": "<string>",
  "provider": "<string>",
  "eventType": "<string>",
  "startTime": "<string>",
  "endTime": "<string>",
  "duration": 123,
  "isRecurring": true,
  "inviteeEmail": "<string>",
  "inviteeName": "<string>"
}
'

import requests

url = "https://api.example.com/api/i/v1/{publicKey}/events"

payload = {
    "visitorId": "<string>",
    "source": "<string>",
    "events": [{}],
    "userIdentity": {},
    "customerIdentity": {},
    "type": "<string>",
    "title": "<string>",
    "eventName": "<string>",
    "properties": {},
    "formId": "<string>",
    "formFields": {},
    "email": "<string>",
    "userId": "<string>",
    "traits": {},
    "customerId": "<string>",
    "customerTraits": {},
    "activeTimeMs": 123,
    "totalTimeMs": 123,
    "sessionId": "<string>",
    "provider": "<string>",
    "eventType": "<string>",
    "startTime": "<string>",
    "endTime": "<string>",
    "duration": 123,
    "isRecurring": True,
    "inviteeEmail": "<string>",
    "inviteeName": "<string>"
}
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: '<string>',
    source: '<string>',
    events: [{}],
    userIdentity: {},
    customerIdentity: {},
    type: '<string>',
    title: '<string>',
    eventName: '<string>',
    properties: {},
    formId: '<string>',
    formFields: {},
    email: '<string>',
    userId: '<string>',
    traits: {},
    customerId: '<string>',
    customerTraits: {},
    activeTimeMs: 123,
    totalTimeMs: 123,
    sessionId: '<string>',
    provider: '<string>',
    eventType: '<string>',
    startTime: '<string>',
    endTime: '<string>',
    duration: 123,
    isRecurring: true,
    inviteeEmail: '<string>',
    inviteeName: '<string>'
  })
};

fetch('https://api.example.com/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://api.example.com/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' => '<string>',
    'source' => '<string>',
    'events' => [
        [
                
        ]
    ],
    'userIdentity' => [
        
    ],
    'customerIdentity' => [
        
    ],
    'type' => '<string>',
    'title' => '<string>',
    'eventName' => '<string>',
    'properties' => [
        
    ],
    'formId' => '<string>',
    'formFields' => [
        
    ],
    'email' => '<string>',
    'userId' => '<string>',
    'traits' => [
        
    ],
    'customerId' => '<string>',
    'customerTraits' => [
        
    ],
    'activeTimeMs' => 123,
    'totalTimeMs' => 123,
    'sessionId' => '<string>',
    'provider' => '<string>',
    'eventType' => '<string>',
    'startTime' => '<string>',
    'endTime' => '<string>',
    'duration' => 123,
    'isRecurring' => true,
    'inviteeEmail' => '<string>',
    'inviteeName' => '<string>'
  ]),
  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://api.example.com/api/i/v1/{publicKey}/events"

	payload := strings.NewReader("{\n  \"visitorId\": \"<string>\",\n  \"source\": \"<string>\",\n  \"events\": [\n    {}\n  ],\n  \"userIdentity\": {},\n  \"customerIdentity\": {},\n  \"type\": \"<string>\",\n  \"title\": \"<string>\",\n  \"eventName\": \"<string>\",\n  \"properties\": {},\n  \"formId\": \"<string>\",\n  \"formFields\": {},\n  \"email\": \"<string>\",\n  \"userId\": \"<string>\",\n  \"traits\": {},\n  \"customerId\": \"<string>\",\n  \"customerTraits\": {},\n  \"activeTimeMs\": 123,\n  \"totalTimeMs\": 123,\n  \"sessionId\": \"<string>\",\n  \"provider\": \"<string>\",\n  \"eventType\": \"<string>\",\n  \"startTime\": \"<string>\",\n  \"endTime\": \"<string>\",\n  \"duration\": 123,\n  \"isRecurring\": true,\n  \"inviteeEmail\": \"<string>\",\n  \"inviteeName\": \"<string>\"\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://api.example.com/api/i/v1/{publicKey}/events")
  .header("Content-Type", "application/json")
  .body("{\n  \"visitorId\": \"<string>\",\n  \"source\": \"<string>\",\n  \"events\": [\n    {}\n  ],\n  \"userIdentity\": {},\n  \"customerIdentity\": {},\n  \"type\": \"<string>\",\n  \"title\": \"<string>\",\n  \"eventName\": \"<string>\",\n  \"properties\": {},\n  \"formId\": \"<string>\",\n  \"formFields\": {},\n  \"email\": \"<string>\",\n  \"userId\": \"<string>\",\n  \"traits\": {},\n  \"customerId\": \"<string>\",\n  \"customerTraits\": {},\n  \"activeTimeMs\": 123,\n  \"totalTimeMs\": 123,\n  \"sessionId\": \"<string>\",\n  \"provider\": \"<string>\",\n  \"eventType\": \"<string>\",\n  \"startTime\": \"<string>\",\n  \"endTime\": \"<string>\",\n  \"duration\": 123,\n  \"isRecurring\": true,\n  \"inviteeEmail\": \"<string>\",\n  \"inviteeName\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/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\": \"<string>\",\n  \"source\": \"<string>\",\n  \"events\": [\n    {}\n  ],\n  \"userIdentity\": {},\n  \"customerIdentity\": {},\n  \"type\": \"<string>\",\n  \"title\": \"<string>\",\n  \"eventName\": \"<string>\",\n  \"properties\": {},\n  \"formId\": \"<string>\",\n  \"formFields\": {},\n  \"email\": \"<string>\",\n  \"userId\": \"<string>\",\n  \"traits\": {},\n  \"customerId\": \"<string>\",\n  \"customerTraits\": {},\n  \"activeTimeMs\": 123,\n  \"totalTimeMs\": 123,\n  \"sessionId\": \"<string>\",\n  \"provider\": \"<string>\",\n  \"eventType\": \"<string>\",\n  \"startTime\": \"<string>\",\n  \"endTime\": \"<string>\",\n  \"duration\": 123,\n  \"isRecurring\": true,\n  \"inviteeEmail\": \"<string>\",\n  \"inviteeName\": \"<string>\"\n}"

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

200

{
  "success": true,
  "processed": 123,
  "errors": [
    {}
  ]
}

Endpoint

POST https://app.outlit.ai/api/i/v1/{publicKey}/events

Path Parameters

publicKey · string · required

Your organization’s public key. Starts with pk_.

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
    }
  ]
}

Body Parameters

visitorId · string

Unique identifier for the visitor (UUID format). Required for browser (client) tracking. For server-side tracking (server source), this can be omitted; identity or attribution is derived from email, userId, fingerprint, or customerId in the events.

source · string · default: "client"

Event source. One of: client (browser), server, integration.

events · array · required

Array of event objects to ingest (max 100 per request).

userIdentity · object

Optional user identity for immediate resolution. Used by browser SDK when user is logged in (via setUser()). Allows direct identity resolution instead of anonymous visitor flow.

Property	Type	Description
email	string	User’s email address
userId	string	Your system-owned user/contact ID
traits	object	User/contact traits

customerIdentity · object

Optional customer/account attribution for the whole batch. Used by browser SDK when the current user carries account/workspace context.

Property	Type	Description
customerId	string	Your system-owned customer/account/workspace ID
customerTraits	object	Customer/account traits

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
}

type · string · required

Must be "pageview".

title · string

Page title.

---

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
}

type · string · required

Must be "custom".

eventName · string · required

Name of the custom event.

properties · object

Key-value pairs of event properties. Values can be string, number, boolean, or null.

---

Form Event

Track a form submission.

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

type · string · required

Must be "form".

formId · string

Identifier for the form (ID attribute or name).

formFields · object

Key-value pairs of form field values.

Sensitive fields (password, credit_card, ssn, etc.) are automatically stripped on the server. Don’t send them.

---

Identify Event

Identify the visitor with their email/userId.

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

type · string · required

Must be "identify".

email · string

User’s email address. At least one of email or userId required.

userId · string

Your system-owned user/contact ID.

traits · object

Properties to set on the user profile.

customerId · string

Your system-owned customer/account/workspace ID. Send it with an identify event when you want that external account/workspace to link to the contact resolved from email or userId.

customerTraits · object

Properties to set on the customer profile.

---

Engagement Event

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

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

type · string · required

Must be "engagement".

activeTimeMs · number · required

Time in milliseconds the user was actively engaged (visible tab + user interactions).

totalTimeMs · number · required

Total wall-clock time in milliseconds on the page.

sessionId · string · required

Session ID (UUID) for grouping engagement events. Resets after 30 min of inactivity or tab close.

---

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
}

type · string · required

Must be "calendar".

provider · string · required

Calendar provider: "cal.com", "calendly", or "unknown".

eventType · string

Meeting type name (e.g., “30 Minute Demo”).

startTime · string

Scheduled start time (ISO 8601 format).

endTime · string

Scheduled end time (ISO 8601 format).

duration · number

Duration in minutes.

isRecurring · boolean

Whether this is a recurring meeting.

inviteeEmail · string

Invitee’s email (only available via server-side webhooks).

inviteeName · string

Invitee’s name (only available via server-side webhooks).

---

Response

Success Response

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

success · boolean

Whether the request was successful.

processed · number

Number of events successfully processed.

errors · array

Array of processing errors (only present if some events failed).

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://[e-mail]",
        "path": "/",
        "email": "[e-mail]",
        "userId": "usr_123",
        "customerId": "cust_123",
        "traits": {
          "name": "Jane Doe",
          "plan": "pro"
        },
        "customerTraits": {
          "plan": "pro"
        }
      },
      {
        "type": "custom",
        "url": "server://[e-mail]",
        "path": "/",
        "eventName": "subscription_created",
        "email": "[e-mail]",
        "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://[e-mail]',
                'path': '/',
                'email': '[e-mail]',
                '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://[e-mail]",
      "path": "/",
      "eventName": "payment_received",
      "email": "[e-mail]",
      "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:

1. Batch events - Send multiple events per request (up to 100)
2. Use background queue - Don’t block user actions
3. Retry with backoff - Handle temporary failures
4. 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)