Getting started

Quickstart Guide

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

Before you begin

Complete these steps in the Lehnz dashboard before writing any code.

Create your account

Sign up at lehnz.com with your name, email, and organization name. Click the verification link within 24 hours to activate, then sign in.

Generate your API key pair

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). Required fields: item_id, item_type, and status. Everything else goes in attributes.

Upload user data

Go to Data Ingestion → Users and upload a CSV or JSON file with your user profiles. Required fields: user_id, status, and created_at. Richer attributes improve recommendation quality.

Step 1: Track your first event

Fire an event whenever a user interacts with your catalog. Use your publishable key (safe to call from the browser). The body is an array, so you can batch multiple events in one request.

curl -X POST https://api.lehnz.com/v1/ingest/events/ingest \
  -H "X-API-KEY: lehnz_pk_YOUR_KEY" \
  -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 accepted", "data": { "accepted": 1 }, "error": null }

See Tracking Events for all event types and advanced usage.

Step 2: Get your first recommendation

Pass a strategy (default personalized) and a user_id. Lehnz returns a ranked list of item IDs; look up full product details from your own database using those IDs. Use your publishable key.

curl -X POST https://api.lehnz.com/v1/recommend \
  -H "X-API-KEY: lehnz_pk_YOUR_KEY" \
  -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_match" }],
    "pagination": { "page": 1, "limit": 10, "total_count": 48, "has_next": true }
  },
  "error": null
}

See Recommendations for the full integration pattern including attribution tracking.