Applications

These endpoints are specific to application connections.

Preview send event

Returns a preview of an event as it would be sent to an application. The event is not actually delivered.

Request

  • :id

    int Required

    The ID of the destination application connection through which the event would be sent.

  • type

    string Required

    The ID of the event type to be sent. It must be one of the event types supported by the application connection.

  • event

    object Required

    The event (as it would be received from an SDK or webhook connection) that is sent to the application.

    • event.connectionId

      int

      The ID of the source connection from which the event originates. Automatically set by Krenalis when the event is received.

    • event.anonymousId

      string

      A unique identifier assigned to a user before authentication, used to track anonymous activity across sessions.

    • event.channel

      string

      The source channel through which the event was received (e.g., web, mobile, server).

    • event.category

      string

      It is used to group related pages or screens for analysis and reporting.

    • event.context

      object

      Information about the environment where the event occurred. If there's no information in the context, this field is not returned.

      • event.context.app

        object

        The application that sent the event.

        • event.context.app.name

          string

          The application name.

        • event.context.app.version

          string

          The application version.

        • event.context.app.build

          string

          The application build identifier.

        • event.context.app.namespace

          string

          The application namespace or internal identifier.

      • event.context.browser

        object

        The browser from which the event originated.

        • event.context.browser.name

          string

          The name of the browser from which the event originated.

          If the value is "Other", then the field other is populated with the browser name.

          Possible values: "Chrome", "Safari", "Edge", "Firefox", "Samsung Internet", "Opera" or "Other".

        • event.context.browser.other

          string

          The name of the browser in case it is not one of those recognized by Krenalis.

          This field is present only when name is "Other".

        • event.context.browser.version

          string

          The version of the browser from which the event originated.

      • event.context.campaign

        object

        The campaign that originated the event.

        • event.context.campaign.name

          string

          The campaign name.

        • event.context.campaign.source

          string

          The campaign source.

        • event.context.campaign.medium

          string

          The campaign medium (e.g. "email", "social").

        • event.context.campaign.term

          string

          The campaign keyword or term.

        • event.context.campaign.content

          string

          The campaign content or variation.

      • event.context.device

        object

        The device from which the event originated.

        For iOS, note that model identifiers may differ from marketed names (e.g., "iPhone16,2" for iPhone 15 Pro Max).

        • event.context.device.id

          string

          The device identifier.

        • event.context.device.advertisingId

          string

          The advertising identifier.

        • event.context.device.adTrackingEnabled

          boolean

          Indicates whether ad tracking is enabled.

        • event.context.device.manufacturer

          string

          The device manufacturer.

        • event.context.device.model

          string

          The device model.

        • event.context.device.name

          string

          The device name.

        • event.context.device.type

          string

          The device type (e.g., mobile, desktop).

        • event.context.device.token

          string

          The unique device token.

      • event.context.ip

        ip

        The IP address associated with the event.

      • event.context.library

        object

        The analytics library used to send the event.

        • event.context.library.name

          string

          The name of the analytics library.

        • event.context.library.version

          string

          The version of the analytics library.

      • event.context.locale

        string

      • event.context.location

        object

        Device location from which the event was originated.

        • event.context.location.city

          string

          The city.

        • event.context.location.country

          string

          The country.

        • event.context.location.latitude

          float

          The latitude.

        • event.context.location.longitude

          float

          The longitude.

        • event.context.location.speed

          float

          The speed at which the device is moving, in meters per second.

      • event.context.network

        object

        The network to which the device originating the event was connected.

        • event.context.network.bluetooth

          boolean

          Indicates whether Bluetooth is active.

        • event.context.network.carrier

          string

          The mobile network carrier name.

        • event.context.network.cellular

          boolean

          Indicates whether a cellular connection is active.

        • event.context.network.wifi

          boolean

          Indicates whether Wi-Fi is active.

      • event.context.os

        object

        The OS of the device or browser from which the event was originated.

        • event.context.os.name

          string

          The name of the OS from which the event was originated.

          If the value is "Other", then the field other is populated with the OS name.

          Possible values: "Android", "Windows", "iOS", "macOS", "Linux", "Chrome OS" or "Other".

        • event.context.os.other

          string

          The name of the OS in case it is not one of those recognized by Krenalis.

          This field is present only when name is "Other".

        • event.context.os.version

          string

          The version of the OS.

      • event.context.page

        object

        The page where the event originated.

        • event.context.page.path

          string

          The page path.

        • event.context.page.referrer

          string

          The referring URL.

        • event.context.page.search

          string

          The URL search parameters.

        • event.context.page.title

          string

          The page title.

        • event.context.page.url

          string

          The full page URL.

      • event.context.referrer

        object

        The URL of the page or source that referred the user to the page where the event originated.

        • event.context.referrer.id

          string

          The identifier of the referring source (e.g., campaign or partner ID).

        • event.context.referrer.type

          string

          The source category of the referrer (e.g., search, social, email).

      • event.context.screen

        object

        The screen of the app where the event was originated.

        • event.context.screen.width

          16 bit int

          The screen width.

        • event.context.screen.height

          16 bit int

          The screen height.

        • event.context.screen.density

          decimal(3, 2)

          The screen density. It is a positive number.

      • event.context.session

        object

        The user session when the event was generated.

        • event.context.session.id

          64 bit int

          The session identifier.

        • event.context.session.start

          boolean

          Indicates whether the event started a session.

      • event.context.timezone

        string

        The user's timezone as a tzdata string (e.g., "America/New_York").

      • event.context.userAgent

        string

        The device identifier from which the event originated.

    • event.event

      string

      Identifies a track-type event, for example with a value like Product Purchased. For any other event type, it is never returned.

    • event.groupId

      string

      The group ID related to the event. Returned only for group-type event, and absent for all other event types.

    • event.messageId

      string

      The ID that uniquely identifies the event.

    • event.name

      string

      The title of the viewed page or screen in page and screen events. Not returned for other event types.

    • event.properties

      json

      A key–value pairs describing contextual details about the event (e.g., product_id, revenue, rating). Distinct from traits, which describe user attributes.

    • event.receivedAt

      datetime

      An UTC timestamp indicating when the event was received. Set by Krenalis.

    • event.sentAt

      datetime

      An UTC timestamp indicating when the event was sent by the client. Not reliable for analysis due to potential client clock drift; use timestamp for analytics.

    • event.originalTimestamp

      datetime

      An UTC timestamp indicating when the event occurred on the client, in ISO 8601 format. Not recommended for analysis due to possible clock drift; use timestamp instead.

    • event.timestamp

      datetime

      An UTC timestamp indicating when the event occurred, in ISO 8601 format. Suitable for analysis.

    • event.traits

      json

      A key–value pairs containing user information (e.g., name, email, plan).

      This field is always returned, regardless of the event type.

      If there are no traits, an empty JSON object is returned.

    • event.type

      string

      The event type: one of "page", "screen", "track", "identify", "group", or "alias".

      Possible values: "alias", "identify", "group", "page", "screen" or "track".

    • event.previousId

      string

      The user's previous identifier.

    • event.userId

      string

      The unique identifier assigned to a user after authentication. If absent, the user is anonymous.

  • transformation

    object Conditionally Required

    The transformation.

    It is required if the event type schema contains even one required property.

    • transformation.mapping

      nullable object with string values Conditionally Required

      mapping

    • transformation.function

      nullable object Conditionally Required

      transformation function

      • transformation.function.source

        string

        source code

      • transformation.function.language

        string

        language

        Possible values: "JavaScript" or "Python".

      • transformation.function.preserveJSON

        boolean

        Preserve JSON

  • outSchema

    schema Conditionally Required

    The output schema.

    It is required if the transformation has been provided.

Response

No response.
POST /v1/connections/:id/preview-send-event
curl https://example.com/v1/connections/1371036433/preview-send-event \
-H "Authorization: Bearer api_xxxxxxx" \
--json '{
"type": "addToCart",
"event": {
"connectionId": 1371036433,
"anonymousId": "3e93e10e-5ca0-4a8c-bef6-cf9197b37729",
"context": {
"browser": {
"name": "Safari",
"version": "17.2.1"
},
"ip": "172.91.24.57",
"library": {
"name": "krenalis.js",
"version": "1.0.0"
},
"locale": "en-US",
"os": {
"name": "macOS",
"version": "14.5"
},
"page": {
"path": "/dashboard",
"title": "User Dashboard",
"url": "https://app.example.com/dashboard"
},
"screen": {
"width": 3024,
"height": 1964,
"density": 2
},
"session": {
"id": "1766272512048"
},
"timezone": "America/Los_Angeles",
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_5) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.2.1 Safari/605.1.15"
},
"event": "Workout Completed",
"messageId": "82c8516b-434b-48f4-a32c-a6369e1543fd",
"properties": {
"workout_type": "Cardio",
"duration_minutes": 45,
"calories_burned": 380,
"device": "Smartwatch"
},
"receivedAt": "2025-10-20T16:15:24.340Z",
"sentAt": "2025-10-20T16:15:24.327Z",
"originalTimestamp": "2025-10-20T16:15:23.992Z",
"timestamp": "2025-10-20T16:15:24.010Z",
"type": "track",
"userId": "720572415"
},
"transformation": {
"mapping": {
"eventName": "event",
"attributes": "properties"
}
},
"outSchema": {
"kind": "object",
"properties": [
{
"name": "eventName",
"type": {
"kind": "string"
}
},
{
"name": "attributes",
"type": {
"kind": "map",
"elementType": {
"kind": "json"
}
}
}
]
}
}'
Errors
404
workspace does not exist
404
connection does not exist
422
connection does not have the event type
422
event is invalid
422
output schema is not compatible with the event type's schema
422
transformation failed
422
transformation language is not supported

List application users

Retrieves a set of users directly from the external application connected through the specified connection (e.g., contacts from a HubSpot account or the profiles of a Klaviyo account).

This method can be used to retrieve a sample of users from an application, for example for debugging purposes or to display them in an interface, before actually importing users into Krenalis through a pipeline.

If you need the unified profiles stored in your data warehouse, see the List profiles endpoint.

Request

  • :id

    int Required

    The ID of the application connection from which to read users.

  • schema

    schema Required

    The schema that the returned users must satisfy

  • filter

    object

    The filter applied to the users. If not empty, only users that match the filter will be returned.

    • filter.logical

      string Required Possible values: "and" or "or".

    • filter.conditions

      array of object Required

      A filter's condition.

      • property

        string Required

        The name or path of the property. If the property has a json type, it can include a json path.

      • operator

        string Required

        The condition's operator. The allowed values depend on the property's type.

        Possible values: "is", "is not", "is less than", "is less than or equal to", "is greater than", "is greater than or equal to", "is between", "is not between", "contains", "does not contain", "is one of", "is not one of", "starts with", "ends with", "is before", "is on or before", "is after", "is on or after", "is true", "is false", "is empty", "is not empty", "is null", "is not null", "exists" or "does not exist".

      • values

        array of string

        The values the operator applies to, if any. These depend on both the operator and the property's type, including whether they're present and how many there are.

  • cursor

    string

    The cursor used to fetch the next set of users. If missing or empty, it returns the first set of users.

Response

  • users

    array of object with json values

    The application users from the provided cursor.

  • cursor

    string

    The cursor to be passed to retrieve the next set of users. If there are no more users, the cursor will be empty.
GET /v1/connections/:id/users
curl -G https://example.com/v1/connections/1371036433/users \
-H "Authorization: Bearer api_xxxxxxx" \
-d "schema=%7b%0a%09%09%09%09%09%09%09%22kind%22%3a%20%22object%22,%0a%09%09%09%09%09%09%09%22properties%22%3a%20%5b%0a%09%09%09%09%09%09%09%09%7b%0a%09%09%09%09%09%09%09%09%09%22name%22%3a%20%22email%22,%0a%09%09%09%09%09%09%09%09%09%22type%22%3a%20%7b%20%22kind%22%3a%20%22string%22,%20%22maxLength%22%3a%20120%20%7d%0a%09%09%09%09%09%09%09%09%7d%0a%09%09%09%09%09%09%09%5d%0a%09%09%09%09%09%09%7d"
Response
{
  "users": [
    {
      "id": "30cae655-4f86-4696-ae2c-2c9105b282ba"
    }
  ],
  "cursor": "x9F2abQ7mP0rL8tVz3Kd"
}
Errors
404
workspace does not exist
404
connection does not exist
422
schema is not aligned with the application's source schema

Get application user schemas

Returns the source and destination user schema of an application connection. The connection must be an application connection that supports users.

Request

  • :id

    int Required

    The ID of the application connection. It must support users.

Response

  • schemas

    object

    The profile schemas of the application connection.

    • schemas.source

      schema

      The source schema.

    • schemas.destination

      schema

      The destination schema. It is null for source connections.
GET /v1/connections/:id/schemas/user
curl https://example.com/v1/connections/1371036433/schemas/user \
-H "Authorization: Bearer api_xxxxxxx"
Response
{
  "schemas": {
    "source": {
      "kind": "object",
      "properties": [
        {
          "name": "first_name",
          "type": {
            "kind": "string",
            "charLen": 60
          }
        },
        {
          "name": "last_name",
          "type": {
            "kind": "string",
            "charLen": 60
          }
        }
      ]
    },
    "destination": {
      "kind": "object",
      "properties": [
        {
          "name": "first_name",
          "type": {
            "kind": "string",
            "charLen": 60
          },
          "createRequired": true
        },
        {
          "name": "last_name",
          "type": {
            "kind": "string",
            "charLen": 60
          },
          "createRequired": true
        }
      ]
    }
  }
}
Errors
404
workspace does not exist
404
connection does not exist

Get event type schema

Returns the schema for a specified event type in a connection. The connection must be a destination application connection that supports events.

Request

  • :id

    int Required

    The ID of the destination application connection. It must support events.

  • type

    string Required

    The ID of the event type.

Response

  • schema

    schema

    The schema of the event type. It is null if the event type does not have a schema.
GET /v1/connections/:id/schemas/event
curl -G https://example.com/v1/connections/1371036433/schemas/event \
-H "Authorization: Bearer api_xxxxxxx" \
-d "type=page_view"
Response
{
  "schema": {
    "kind": "object",
    "properties": [
      {
        "name": "eventName",
        "type": {
          "kind": "string"
        }
      },
      {
        "name": "attributes",
        "type": {
          "kind": "map",
          "elementType": {
            "kind": "json"
          }
        }
      }
    ]
  }
}
Errors
404
workspace does not exist
404
connection does not exist
404
event type does not exist