---
title: "Ingest events"
method: POST
path: "/api/i/v1/{publicKey}/events"
tags: ["Ingest API"]
---

# Ingest events

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

Send tracking events to Outlit. The public key in the URL path identifies the workspace; no secret bearer token is required for this endpoint.

## Path parameters

- `publicKey` string, required

## Request body

- IngestEventsRequest
  - `visitorId` string, uuid — Browser visitor identifier. Required for client tracking.
  - `source` 'client' | 'server' | 'integration'
  - `userIdentity` UserIdentity
    - `email` string, email
    - `userId` string
    - `traits` JsonObject
  - `customerIdentity` CustomerIdentity
    - `customerId` string
    - `customerTraits` JsonObject
  - `events` IngestEvent[], required
    - union
      - PageviewEvent
        - `type` 'pageview', required
        - `timestamp` number — Unix timestamp in milliseconds.
        - `url` string, uri
        - `path` string
        - `referrer` string
        - `utm` UtmParameters
          - `source` string
          - `medium` string
          - `campaign` string
          - `term` string
          - `content` string
        - `title` string
      - CustomEvent
        - `type` 'custom', required
        - `timestamp` number — Unix timestamp in milliseconds.
        - `url` string, uri
        - `path` string
        - `referrer` string
        - `utm` UtmParameters
          - `source` string
          - `medium` string
          - `campaign` string
          - `term` string
          - `content` string
        - `eventName` string, required
        - `properties` JsonObject
      - FormEvent
        - `type` 'form', required
        - `timestamp` number — Unix timestamp in milliseconds.
        - `url` string, uri
        - `path` string
        - `referrer` string
        - `utm` UtmParameters
          - `source` string
          - `medium` string
          - `campaign` string
          - `term` string
          - `content` string
        - `formId` string
        - `formFields` JsonObject
      - IdentifyEvent
        - `type` 'identify', required
        - `timestamp` number — Unix timestamp in milliseconds.
        - `url` string, uri
        - `path` string
        - `referrer` string
        - `utm` UtmParameters
          - `source` string
          - `medium` string
          - `campaign` string
          - `term` string
          - `content` string
        - `email` string, email
        - `userId` string
        - `customerId` string
        - `traits` JsonObject
        - `customerTraits` JsonObject
      - EngagementEvent
        - `type` 'engagement', required
        - `timestamp` number — Unix timestamp in milliseconds.
        - `url` string, uri
        - `path` string
        - `referrer` string
        - `utm` UtmParameters
          - `source` string
          - `medium` string
          - `campaign` string
          - `term` string
          - `content` string
        - `activeTimeMs` number, required
        - `totalTimeMs` number, required
        - `sessionId` string, uuid, required
      - CalendarEvent
        - `type` 'calendar', required
        - `timestamp` number — Unix timestamp in milliseconds.
        - `url` string, uri
        - `path` string
        - `referrer` string
        - `utm` UtmParameters
          - `source` string
          - `medium` string
          - `campaign` string
          - `term` string
          - `content` string
        - `provider` 'cal.com' | 'calendly' | 'unknown', required
        - `eventType` string
        - `startTime` string, date-time
        - `endTime` string, date-time
        - `duration` number
        - `isRecurring` boolean
        - `inviteeEmail` string, email
        - `inviteeName` string
      - StageEvent
        - `type` 'stage', required
        - `timestamp` number — Unix timestamp in milliseconds.
        - `url` string, uri
        - `path` string
        - `referrer` string
        - `utm` UtmParameters
          - `source` string
          - `medium` string
          - `campaign` string
          - `term` string
          - `content` string
        - `stage` 'activated' | 'engaged' | 'inactive', required
        - `properties` JsonObject
      - BillingEvent
        - `type` 'billing', required
        - `timestamp` number — Unix timestamp in milliseconds.
        - `url` string, uri
        - `path` string
        - `referrer` string
        - `utm` UtmParameters
          - `source` string
          - `medium` string
          - `campaign` string
          - `term` string
          - `content` string
        - `status` 'trialing' | 'paid' | 'churned', required
        - `customerId` string
        - `stripeCustomerId` string
        - `properties` JsonObject

## Response `200`

Events accepted.

- IngestEventsSuccess
  - `success` true, required

## Other responses

- `400` — Invalid request body or event payload.
- `403` — Invalid public key or unauthorized domain.
- `429` — Rate limit exceeded.
- `500` — Internal server error.

---

[API](https://skmtc.dev/outlitai/apis/outlit-api.md) · [All operations](https://skmtc.dev/outlitai/apis/outlit-api/llms.txt) · [OpenAPI document](https://skmtc.dev/outlitai/apis/outlit-api/revisions/7e4ecacaa07f?raw)