Getting started

Quickstart Guide

Go from zero to your first real-time personalized recommendation in under 10 minutes.

Prerequisites & Setup

Complete these initial steps in the Lehnz Dashboard before writing integration code.

Create your Organization & Project

Sign up at lehnz.com to access your multi-tenant developer console. Signup requires your organization name and a domain (industry/vertical, e.g. E-commerce, Media, Travel). This can be changed later from organization settings.

Generate your Dual API Keys

Navigate to Developer Access → API Keys and click Generate Key Pair. You will receive two distinct keys for client and server operations:

Key Type	Prefix	Recommended Scope
Publishable Key	`lehnz_pk_live_...`	Browser & Mobile SDKs (Client-side event tracking)
Secret Key	`lehnz_sk_live_...`	Backend & Server-to-server endpoints (Recommendation queries & admin ops)

Secret Key Security

Your secret key is only displayed once upon creation. Store it securely in your server environment variables (.env.local). Never expose it in client-side code.

Ingest Catalog & User Data

Populate your catalog items and initial user profiles using the Data Ingestion API or Dashboard CSV Uploader:

Items Catalog: CSV or JSON array containing item_id, item_type, status (active | inactive | deleted), title, and custom attributes.
User Profiles: CSV or JSON containing user_id, status (active | inactive | deleted), created_at, and optional user attributes.

Step 1: Stream Behavioral Events

Track real-time user activity (views, clicks, purchases) by dispatching events to the Lehnz Ingestion API. Use your Publishable Key (lehnz_pk_live_...).

POST/v1/events/ingest

curl -X POST https://api.lehnz.com/v1/events/ingest \
  -H "X-API-KEY: lehnz_pk_live_123456789" \
  -H "Content-Type: application/json" \
  -d '[{
    "user_id": "usr_123",
    "event_family": "exposure",
    "event_name": "view",
    "item_id": "prod_456"
  }]'

202 Accepted
{
  "success": true,
  "message": "events queued",
  "data": { "accepted": 1 },
  "error": null
}

Batch Event Dispatching

The ingestion API accepts JSON arrays, so you can batch multiple interaction events in a single payload.

Step 2: Fetch Real-Time Personalization

Query the serving endpoint to receive ranked, personalized recommendations tailored to the specified user_id. Use your Secret Key (lehnz_sk_live_...) for secure server-side fetching.

POST/v1/recommend

curl -X POST https://api.lehnz.com/v1/recommend \
  -H "X-API-KEY: lehnz_sk_live_987654321" \
  -H "Content-Type: application/json" \
  -d '{
    "strategy": "personalized",
    "user_id": "usr_123",
    "limit": 10
  }'

200 OK
{
  "success": true,
  "message": "Success",
  "data": {
    "recommendation_id": "550e8400-e29b-41d4-a716-446655440000",
    "strategy": "personalized",
    "recommended_items": ["prod_7", "prod_3", "prod_22"],
    "results": [
      { "item_id": "prod_7", "score": 0.985, "reason": "behavioral_affinity" },
      { "item_id": "prod_3", "score": 0.941, "reason": "co_viewed" },
      { "item_id": "prod_22", "score": 0.890, "reason": "category_match" }
    ],
    "pagination": { "page": 1, "limit": 10, "total_count": 48, "has_next": true }
  },
  "error": null
}

Previous Step

← Welcome

What Lehnz is and what you can build with it.

Next Step

API Reference →

Every endpoint, header, status code, and error schema.