# Apache Unomi - Open Source Customer Data Platform

> Apache Unomi (pronounced "You know me") is a Java open source Customer Data Platform (CDP) hosted at the Apache Software Foundation. It manages customer, lead, and visitor data, enables real-time personalization of customer experiences, and provides built-in privacy management including GDPR compliance. It is the reference implementation of the OASIS Customer Data Platform (CDP) specification.

## Key Facts

- **Project**: Apache Unomi
- **Type**: Customer Data Platform (CDP)
- **License**: Apache License 2.0
- **Language**: Java
- **Runtime**: Apache Karaf (OSGi); Java 17+ required (runtime baseline, not a marketed feature)
- **Storage**: Elasticsearch 9.x (e.g. 9.4.3) or OpenSearch 3.x (Unomi 3.1)
- **API**: REST/JSON & GraphQL
- **Current Stable Version**: 3.1.0 (Apache Unomi 3 product leap)
- **Website**: https://unomi.apache.org
- **Source Code**: https://github.com/apache/unomi
- **Issue Tracker**: https://issues.apache.org/jira/browse/UNOMI
- **Standard**: Reference implementation of OASIS CXS CDP specification

## Core Features

- **Profile Management**: Unified customer profiles aggregated from multiple data sources (web, mobile, CRM, IoT)
- **Event Tracking**: Collect events from any source via REST API (page views, clicks, logins, custom events)
- **Real-time Segmentation**: Dynamic audience segments based on profile properties and event history
- **Scoring**: Lead scoring and engagement scoring with configurable rules
- **Rules Engine**: Built-in rule engine that triggers actions when conditions are met on events or profiles
- **Privacy / GDPR**: Consent management, data anonymization, profile deletion, data portability
- **Plugin Architecture**: Extend functionality through OSGi plugins, Groovy actions, and JSON descriptors
- **Connectors**: MailChimp and custom connectors via plugin API (Salesforce connector was deprecated)
- **GraphQL API**: Flexible query API for profiles, events, segments, and rules
- **Multi-tenancy (Unomi 3.1 major investment)**: Platform-wide tenant isolation for profiles, events, segments, rules, and schemas; public and private API keys
- **Multi-backend**: Elasticsearch or OpenSearch persistence in Unomi 3.1
- **V2 API compatibility**: Optional mode for phased upgrades from Unomi 2.x clients; 119/119 documented 2.x OpenAPI paths retained in 3.1 (additive APIs)
- **Task scheduler**: Cluster-aware background tasks (`/cxs/tasks`)

## Use Cases

1. **Web Personalization**: Track visitors on CMS-managed websites and personalize content based on profile data and segments
2. **Mobile Analytics**: Backend for native mobile apps to collect events, track user journeys, and build profiles
3. **Centralized Profile Management**: Aggregate customer data from CRM, support, commerce, and other systems into unified profiles
4. **Multi-tenant / SaaS CDP**: One Unomi cluster hosting many isolated tenants (agencies, platforms, control planes)
5. **AI-agent customer memory (bidirectional)**: Agents retrieve profiles/events/segments, store observations as events or profile properties, summarize history into profile briefs, and can propose or query segments and rules — via REST/GraphQL with consent gates. Unomi is not an LLM; it is the CDP data layer beside one.

## CDP in an AI-First World

**Message hierarchy for humans and agents:** (1) Apache Unomi 3 major release · (2) Multi-tenancy as the platform leap in 3.1 · (3) AI agents as customer-memory use case.

AI agents and language models are only as good as the data they can access *and* update safely. Apache Unomi 3 provides privacy-compliant customer memory:

- **Retrieve**: Profiles, segments, scores, and event history for LLM/agent context
- **Store**: Write agent observations and preferences back to the CDP
- **Summarize**: Produce profile briefs (synchronously or via Unomi task scheduling)
- **Operate**: Propose/create segments, adjust scores, drive rules and personalization
- **Govern**: GDPR consent management gates agent tool access
- **Open & vendor-neutral**: Connect OpenAI, Anthropic, local models, MCP tools, or custom pipelines — your choice
- **Unomi 3 hooks**: Multi-tenancy/API keys, additive REST (119/119 documented 2.x paths retained in 3.1), OpenSearch or Elasticsearch, V2 compatibility mode

Blog: https://unomi.apache.org/blog/
- Unomi 3 intro: https://unomi.apache.org/blog/introducing-apache-unomi-3.html
- Multi-tenancy: https://unomi.apache.org/blog/unomi-3-multitenancy.html
- AI agents: https://unomi.apache.org/blog/unomi-3-ai-agents.html
- Migrate from 2.x: https://unomi.apache.org/blog/migrating-to-unomi-3.html

## Getting Started (Unomi 3.1)

The fastest way to try Apache Unomi 3.1 is with Docker Compose (Elasticsearch 9.4.3 or OpenSearch 3.x):

```
docker compose up
```

Then create a tenant (`POST /cxs/tenants` as `karaf:karaf`), regenerate keys via `POST /cxs/tenants/{id}/apikeys?type=PUBLIC|PRIVATE` (save each `plainTextKey` — create only returns `maskedKey`), and create a scope before context/events:

- **Public key** → header `X-Unomi-Api-Key` for `/cxs/context.json` and `/cxs/eventcollector`
- **Private key** → basic auth `tenantId:privateApiKey` for admin APIs (scopes, rules, schemas, searches)
- **Scope** → `POST /cxs/scopes` before any context or event that references that scope id

System admin (`karaf:karaf`) is for tenant management and cluster operations, not for public context/event calls in native 3.1 mode.

Full getting started guide: https://unomi.apache.org/get-started.html
Docker quick start: https://unomi.apache.org/get-started.html#quickstart
Auth overview: https://unomi.apache.org/get-started.html#auth
Tutorials: https://unomi.apache.org/tutorial.html

## Documentation

- Main documentation: https://unomi.apache.org/documentation.html
- Latest manual: https://unomi.apache.org/manual/latest/index.html
- REST API reference: https://unomi.apache.org/rest-api-doc/index.html
- Java API (Javadoc): https://unomi.apache.org/unomi-api/apidocs/index.html

## Community & Support

- **Users mailing list**: users@unomi.apache.org (subscribe: users-subscribe@unomi.apache.org)
- **Dev mailing list**: dev@unomi.apache.org (subscribe: dev-subscribe@unomi.apache.org)
- **Slack**: #unomi channel on ASF Slack (https://the-asf.slack.com) — Apache committers sign in with @apache.org email; others can request a guest invitation via users@unomi.apache.org (see https://infra.apache.org/slack.html)
- **Monthly meetings**: The community meets monthly online
- **JIRA**: https://issues.apache.org/jira/browse/UNOMI

## Ecosystem

### Products Built on Apache Unomi
- **Jahia jExperience**: CDP and Digital Experience Platform (initial contributor of Unomi) — https://www.jahia.com
- **Ninetailed Personalization Platform**: Content personalization platform using Unomi — https://ninetailed.io
- **Dropsolid Experience Cloud**: DXP with Drupal CMS, Mautic, and Unomi CDP — https://dropsolid.com
- **Inoyu SaaS**: Fully managed cloud-hosted Unomi service (coming soon)

### Commercial Support
- **Inoyu**: CDP implementations, commercial extensions and support — https://www.inoyu.dev
- **Yupiik**: Expert team and Apache contributors — https://www.yupiik.com

## Architecture

Apache Unomi is a REST server. Data sources (web, mobile, CRM, IoT, AI agents) send events via the REST API with tenant resolution (public API key or private-key basic auth in 3.1). The processing engine stores data in Elasticsearch or OpenSearch, evaluates segments and rules in real-time, and outputs personalization decisions, scores, and data exports. All communication is JSON over HTTP/HTTPS. A GraphQL API is also available for flexible querying of profiles, events, segments, and rules.

## Frequently Asked Questions

- **What is Apache Unomi?** An open source Customer Data Platform (CDP) managed by the Apache Software Foundation that unifies customer data, enables real-time segmentation and personalization, and provides built-in GDPR compliance.
- **What is Apache Unomi 3?** Major CDP release: 3.0 modernizes the platform (Elasticsearch 9 client, Karaf 4.4, persistence clustering; Java 17+). 3.1 is the product leap — especially a platform-wide multi-tenancy refactor with API keys, plus OpenSearch, task scheduler, and V2 compatibility.
- **How do I get started?** Docker Compose, then create a tenant and use API keys: https://unomi.apache.org/get-started.html#quickstart
- **What storage does it use?** Elasticsearch 9.x or OpenSearch 3.x (Unomi 3.1).
- **Does it have a GraphQL API?** Yes — GraphQL alongside REST.
- **Is it GDPR compliant?** Yes, with built-in consent management, data anonymization, profile deletion, and data portability.
- **Can I use it with AI?** Yes — Unomi is privacy-first customer memory for agents (retrieve, store, summarize, operate), not an LLM. REST or GraphQL with consent gates.
- **What is the OASIS CXS standard?** A Customer Data Platform specification from OASIS. Apache Unomi is its reference implementation.