Koala Profile Ingestion API
Endpoints for sending events and traits tied to individual visitors (profiles).
OpenAPI Specification
openapi: 3.0.3
info:
title: Koala Server-Side Account Ingestion Profile Ingestion API
description: 'RESTful server-side API for sending batched events, visitor identifications, and account traits to Koala''s intent data platform. Supports profile-level and account-level batch ingestion for use in backend services, data pipelines, and edge compute environments where the JavaScript snippet cannot run.
'
version: 1.0.0
contact:
name: Koala Developer Docs
url: https://getkoala.com/docs/developer-guides/server-side
termsOfService: https://getkoala.com/legal/terms
servers:
- url: https://api2.getkoala.com/web/projects/{publicApiKey}
description: Koala collection endpoint (replace {publicApiKey} with your workspace public API key)
variables:
publicApiKey:
default: my-public-api-key
description: Your Koala workspace public API key
tags:
- name: Profile Ingestion
description: Endpoints for sending events and traits tied to individual visitors (profiles).
paths:
/batch:
post:
operationId: sendProfileBatch
summary: Send profile-level batch events, identifies, and page views
description: 'Ingests a batch of events, identify calls, and/or page views tied to a single profile (visitor). Each request must include either a `profile_id` (UUID v4 read from the `ko_id` cookie) or an `email`. A maximum of 30 entries each of events, identifies, and page_views per request is enforced. All entries in a single request must belong to the same person.
'
tags:
- Profile Ingestion
parameters:
- name: publicApiKey
in: path
required: true
description: Your Koala workspace public API key
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ProfileBatchRequest'
examples:
identify:
summary: Identify a visitor
value:
profile_id: 3e6a2c18-3b02-40c4-b8d2-1842c193d3ba
email: person@example.com
trackEvent:
summary: Send a custom event
value:
profile_id: 3e6a2c18-3b02-40c4-b8d2-1842c193d3ba
email: netto@getkoala.com
events:
- message_id: abc123-unique-id
type: track
event: Created Account
properties: {}
sent_at: '2022-11-09T23:57:14.776Z'
sendTraits:
summary: Send visitor traits
value:
profile_id: 3e6a2c18-3b02-40c4-b8d2-1842c193d3ba
email: user@example.org
identifies:
- type: identify
sent_at: '2023-11-30T02:51:36.840Z'
traits:
email: user@example.org
billing_plan: pro
vip: true
is_current_customer: true
responses:
'200':
description: Batch accepted
content:
application/json:
schema:
$ref: '#/components/schemas/BatchResponse'
'400':
description: Bad request — missing required identifier or malformed payload
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized — invalid or missing public API key
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Too many requests — rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security: []
components:
schemas:
BatchResponse:
type: object
description: Successful batch acceptance response.
properties:
ok:
type: boolean
description: Indicates the batch was accepted.
example: true
PageView:
type: object
description: A page view event in the Segment-compatible format.
required:
- type
properties:
message_id:
type: string
description: Optional idempotency key.
type:
type: string
enum:
- page
description: Must be "page".
name:
type: string
description: Human-readable page name.
properties:
type: object
description: Arbitrary properties including url, referrer, title, etc.
additionalProperties: true
sent_at:
type: string
format: date-time
description: ISO 8601 timestamp when the page view was captured.
ProfileBatchRequest:
type: object
description: 'Payload for the profile /batch endpoint. Must include at least one of `profile_id` or `email`. Optionally includes up to 30 each of `events`, `identifies`, and `page_views`.
'
properties:
profile_id:
type: string
format: uuid
description: 'UUID v4 anonymous visitor identifier read from the `ko_id` cookie set by the Koala JavaScript pixel.
'
example: 3e6a2c18-3b02-40c4-b8d2-1842c193d3ba
email:
type: string
format: email
description: Known email address of the visitor for identity resolution.
example: person@example.com
events:
type: array
maxItems: 30
description: Custom track events to associate with this profile.
items:
$ref: '#/components/schemas/TrackEvent'
identifies:
type: array
maxItems: 30
description: Identify calls carrying visitor trait data.
items:
$ref: '#/components/schemas/IdentifyCall'
page_views:
type: array
maxItems: 30
description: Page view events to associate with this profile.
items:
$ref: '#/components/schemas/PageView'
anyOf:
- required:
- profile_id
- required:
- email
IdentifyCall:
type: object
description: An identify call carrying visitor-level traits.
required:
- type
properties:
type:
type: string
enum:
- identify
description: Must be "identify".
sent_at:
type: string
format: date-time
description: ISO 8601 timestamp when the identify was generated.
example: '2023-11-30T02:51:36.840Z'
traits:
type: object
description: Arbitrary key-value traits to associate with the visitor.
additionalProperties: true
properties:
email:
type: string
format: email
billing_plan:
type: string
vip:
type: boolean
is_current_customer:
type: boolean
ErrorResponse:
type: object
description: Error response body.
properties:
error:
type: string
description: Human-readable error message.
code:
type: string
description: Machine-readable error code.
TrackEvent:
type: object
description: A custom track event in the Segment-compatible format.
required:
- type
- event
properties:
message_id:
type: string
description: 'Optional idempotency key. If omitted, the event may be captured more than once on retry. Use a UUID or other unique string.
'
example: abc123-unique-id
type:
type: string
enum:
- track
description: Must be "track".
event:
type: string
description: Human-readable event name.
example: Created Account
properties:
type: object
description: Arbitrary key-value properties associated with the event.
additionalProperties: true
sent_at:
type: string
format: date-time
description: ISO 8601 timestamp when the event was generated.
example: '2022-11-09T23:57:14.776Z'
externalDocs:
description: Koala Developer Guides
url: https://getkoala.com/docs/developer-guides/server-side