Getting started

Quickstart Guide

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

Before you begin

These steps happen in the lehnz dashboard — no code required.

Create your account

Sign up at lehnz.com with your name, email, password, and organization name. You'll receive a verification email — click the link within 24 hours to activate your account, then sign in.

Generate your API key pair

From the dashboard, navigate to Developer Access and click Generate Key Pair. You'll receive two keys:

Key	Prefix	Where to use
Publishable key	`lehnz_pk_...`	Browser and client-side code
Secret key	`lehnz_sk_...`	Server-side only — never expose in the browser

The secret key is shown exactly once

Save it to a secrets manager (AWS Secrets Manager, Doppler, etc.) before closing the dialog. If lost, revoke the pair and generate new keys.

Upload your item catalog

Go to Data Ingestion → Items and upload your product catalog as a CSV or JSON file (max 50 MB). The only required field is item_id — everything else goes in attributes.

Upload user data

Go to Data Ingestion → Users and upload a CSV or JSON file with your user profiles. The required field is user_id. Richer user attributes improve recommendation quality.

Step 1 — Track your first event

Fire an event whenever a user interacts with your catalog. Use your publishable key — it's safe to call from the browser.

terminal

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

track.ts

await fetch('https://ingestion.lehnz.com/api/v1/events/ingest', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': process.env.NEXT_PUBLIC_LEHNZ_PUBLISHABLE_KEY,
  },
  body: JSON.stringify([{
    user_id: 'usr_123',
    item_id: 'prod_456',
    event_name: 'view',
  }]),
  keepalive: true,
});

track.py

import requests
 
requests.post(
    'https://ingestion.lehnz.com/api/v1/events/ingest',
    headers={
        'X-API-KEY': 'lehnz_pk_YOUR_KEY',
        'Content-Type': 'application/json',
    },
    json=[{
        'user_id': 'usr_123',
        'item_id': 'prod_456',
        'event_name': 'view',
    }],
)

Response (202 Accepted)

202 means the event was accepted into the processing queue. It's available within seconds.

See Tracking Events for all event types and advanced usage.

Step 2 — Get your first recommendation

Pass a user_id and lehnz returns a ranked list of item IDs. Use your publishable key.

terminal

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

recommendations.ts

const res = await fetch('https://recommendations.lehnz.com/recommend', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': process.env.NEXT_PUBLIC_LEHNZ_PUBLISHABLE_KEY,
  },
  body: JSON.stringify({
    user_id: 'usr_123',
    limit: 10,
  }),
});
 
const { data } = await res.json();
// data.all_item_ids → ["prod_7", "prod_3", "prod_22", ...]
// data.recommendation_id → "rec_abc123"

recommendations.py

import requests
 
res = requests.post(
    'https://recommendations.lehnz.com/recommend',
    headers={
        'X-API-KEY': 'lehnz_pk_YOUR_KEY',
        'Content-Type': 'application/json',
    },
    json={'user_id': 'usr_123', 'limit': 10},
)
 
data = res.json()['data']
# data['all_item_ids'] → ["prod_7", "prod_3", ...]
# data['recommendation_id'] → "rec_abc123"

Response (200 OK)

The response contains item IDs only — look up full product details from your own database using those IDs.

See Recommendations for the full integration pattern with attribution tracking.