# Synerise

> Synerise is an AI-driven behavioral data and customer data platform (CDP).
> It enables businesses to collect, unify, and act on customer data across web, mobile, and offline channels.

## Overview

Synerise provides:
- **Customer data unification** — Merges behavioral data from all channels into unified customer profiles
- **AI-powered personalization** — Recommendations, search, predictions (churn, LTV, purchase likelihood)
- **Marketing automation** — Workflow builder with event-triggered scenarios
- **Omnichannel campaigns** — Email, SMS, mobile push, web push, WhatsApp, in-app, dynamic content
- **Loyalty programs** — Points, vouchers, promotions, gamification, tiers
- **Real-time analytics** — Dashboards, segmentations, funnels, trends, aggregates

## API Servers

| Environment | Base URL |
|---|---|
| Microsoft Azure EU | `https://api.synerise.com` |
| Microsoft Azure USA | `https://api.azu.synerise.com` |
| Google Cloud Platform | `https://api.geb.synerise.com` |

## Authentication

Synerise uses three authentication methods:

### JWT (Bearer Token) — Primary method
Include in header: `Authorization: Bearer {JWT}`
- Generated by login endpoints
- Uses RS512 algorithm
- Public key: `https://api.synerise.com/v4/public.pem`
- Refresh before expiry via `auth/refresh` endpoints

### Tracker Key — For web/recommendation requests
Include as query parameter: `?token={tracker_key}`
- Same key as used in website tracking code
- Used for recommendations, search, and tracker-scoped endpoints

### Basic Auth — For server-to-server
Include in header: `Authorization: Basic base64({workspaceGuid}:{apiKey})`
- Must be enabled per API key in workspace settings
- No token expiration, no refresh needed

## Authorization Flows

### Profile (Client) login — for end users
Token validity: 60 minutes (default)
```
POST /sauth/v3/auth/login/client
Body: { "apiKey": "...", "identityProvider": "SYNERISE", "password": "...", "uuid": "..." }
→ Returns JWT
```

Anonymous login (no credentials):
```
POST /sauth/v3/auth/login/client/anonymous
Body: { "apiKey": "...", "deviceId": "...", "uuid": "..." }
→ Returns JWT
```

### Workspace login — for server-to-server / M2M
Token validity: 60 minutes (default)
```
POST /uauth/v2/auth/login/profile
Body: { "apiKey": "01234abc-1234-5678-9abc-def012345678" }
→ Returns JWT
```

### User login — for Synerise portal users
Multi-step: login → MFA → select workspace
```
POST /uauth/auth/login/user
Body: { "username": "user@company.com", "password": "..." }
→ Returns JWT + mfaMethods

POST /uauth/auth/login/user/profile/{workspaceGuid}
Header: Authorization: Bearer {JWT from step 1}
→ Returns workspace-scoped JWT
```

## API Consumer Scopes

Each endpoint specifies which consumer types can call it:

| Scope | Description |
|---|---|
| Workspace (Business Profile) | Server-to-server integrations using workspace API keys |
| Synerise User | Portal users logged into the Synerise application |
| Profile (Client) | End-user/customer authenticated via profile login |
| Anonymous Profile | Unauthenticated end-user with UUID only |
| Web SDK Tracker | Requests authenticated via tracker key |
| Organization | Organization-level access (contact support) |

## Permission System

Endpoints require specific permissions assigned to API keys or user roles.

**Permission format:** `{SERVICE}_{RESOURCE}_{ACTION}` (e.g., `API_CUSTOM_EVENTS_CREATE`, `ANALYTICS_BACKEND_AGGREGATES_READ`)

**Permission groups** map to the Synerise access management UI:
- `analytics`, `analytics_aggregates`, `analytics_trends`
- `assets_catalogs`, `assets_search`, `assets_schema_builder`, `assets_brickworks`
- `automation_2_journeys`
- `campaigns_promotions`, `campaigns_recommendations`, `campaigns_personalised_promotions`
- `client_detail`, `client_management`, `client_activities`, `client_tags`
- `settings_users`, `settings_customers_iam`, `settings_export`
- `templates`

Special values:
- `NO_TOKEN` — No authentication required
- `ROLE_USER` / `ROLE_PREAUTHORIZED_USER` — Role-based check (portal users)

## Key Concepts

| Term | Definition |
|---|---|
| **Profile** | End-user/customer record. Called "client" in API. Has a UUID. |
| **UUID** | Unique identifier per profile. Stored in cookies (web) or SDK (mobile). |
| **Event** | Recorded action with `action` name and `params`, attributed to a profile. |
| **Workspace** | Organizational container for a company's data and campaigns. Formerly "Business Profile". |
| **Catalog** | Collection of item/product data for recommendations, search, promotions. |
| **Document** | Structured data object stored in Synerise (Schema Builder). |
| **IQL** | Items Query Language — filtering language for search/recommendation requests. |
| **Jinjava** | Templating engine (Jinja2-based) for personalizing content across channels. |
| **Aggregate** | Computed metric from event/profile data for segmentation and personalization. |
| **Expression** | Formula-based calculation on profile/event data for analytics. |
| **Voucher Pool** | Collection of unique voucher codes assignable to profiles. |
| **Dynamic Content** | Personalized content displayed on websites/apps via campaigns. |

## Platform Modules

| Module | Purpose |
|---|---|
| **AI Hub** | Recommendations, AI search, predictions (churn, LTV, propensity) |
| **Automation Hub** | Workflow/scenario builder for automated processes |
| **Behavioral Data Hub** | CRM, profile management |
| **Data Modeling Hub** | Events, catalogs, documents, schema builder |
| **Decision Hub** | Analytics dashboards, metrics, segmentations |
| **Experience Hub** | Campaign management (email, SMS, push, dynamic content) |
| **Settings** | Workspace configuration, IAM, API keys, tracking codes |

## SDKs

- **Web SDK** — JavaScript tracking code for websites. Handles UUID management, event tracking, dynamic content.
- **Android SDK** — Native Android. Auto event tracking, push notifications, in-app messages, recommendations.
- **iOS SDK** — Native iOS. Same capabilities as Android.
- **React Native SDK** — Cross-platform. Manual event triggers required.
- **Flutter SDK** — Cross-platform with Huawei support.

## Common Request Patterns

### Required Headers
- `Authorization: Bearer {JWT}` — on most endpoints
- `Content-Type: application/json` — for request bodies
- `Api-Version: 4.4` — required on `/v4/*` endpoints

### Pagination
Two patterns:
1. **Page-based:** `?page=1&limit=100` (page is 1-indexed, max limit often 1000)
2. **Cursor-based:** `?pageToken={token}` — next/previous tokens returned in response

### Profile Identifiers
Profiles can be identified by: `id` (numeric), `uuid`, `email`, or `custom_identify`.
Use path parameter `identifierType` to specify which one.

### Error Response Format
```json
{
  "error": "Bad Request",
  "status": 400,
  "message": "Description of the problem",
  "path": "/path_of_the_endpoint",
  "errors": [
    { "code": 120, "field": "exampleField", "message": "details" }
  ]
}
```

Common status codes: 200 (success), 202 (accepted/async), 400 (validation), 401 (unauthorized), 403 (forbidden), 404 (not found), 429 (rate limited).

### Rate Limiting
HTTP 429 is returned when rate limits are exceeded. No specific limits are published — use batch endpoints where available and implement exponential backoff.

## Best Practices

- **API keys:** Keep secret. Workspace keys for server-to-server ONLY. Never embed in client apps.
- **Authentication:** Refresh tokens BEFORE expiry. Include space between "Bearer" and token.
- **Headers:** Always include `Api-Version: 4.4` for v4 endpoints. Watch for `X-API-DEPRECATED` response header.
- **HTTPS:** All communication must use TLS 1.2+.
- **Rate limiting:** Implement exponential backoff. Use batch endpoints where available.
- **Profile identification:** Default unique identifier is email (configurable to customId).
- **Events:** Use `POST /v4/events/batch` for sending multiple events efficiently.
- **Web SDK CSP:** Allowlist `*.synerise.com`, `*.snrcdn.net`, `*.snrbox.com`, `*.snrlink-page.com`.
- **Deprecation:** Check `X-API-DEPRECATED` header. Migrate away from deprecated endpoints promptly.

## API Categories (730 endpoints)

Authorization, Data Management (Events, AI Events), Profile Management, Analytics (Aggregates, Funnels, Segmentations, Trends, Metrics, Reports, Expressions, Histograms, Sankeys), AI Recommendations (Campaigns, Configuration), AI Search (Search, Visual Search, Listing, Suggestions, Query Rules, Synonyms, Query Classification), Loyalty (Promotions, Vouchers, Handbills, Points, Settings, Locks), Asset Management (Catalogs, Documents, Screen Views, Templates, Uploader), Campaigns (Workflows), Brickworks (Schemas, Records, External Sources, Content Generation), Settings (Access Control, User Management), Organizations (Consumption).

## Documentation

- [toc.json](/api/toc.json) — Machine-readable table of contents mirroring the live site navigation
- [llms-full.txt](/api/llms-full.txt) — Complete documentation as plain text
- [Full Markdown](/api/docs/llms-full) — All docs as Markdown
- [Single article](/api/docs/{slug}/markdown) — Individual article as Markdown
- [OpenAPI YAML](/api/openapi.yaml) — API specification
- [OpenAPI JSON](/api/openapi.json) — Enriched spec with code samples and permissions
- [API as Markdown](/api/api-reference/markdown) — All endpoints as Markdown