Integration

Load your catalog

Before lehnz can recommend anything, it needs to know what your items and users are. Do the initial bulk load from the dashboard, then keep records in sync with the upsert API.

Item schema

Field	Required	Description
item_id	Yes	Unique within your org. Used as the primary key for recommendations.
item_type	Yes	Item category, e.g. `product`, `video`, `article`.
status	Yes	`active` (recommendable) \| `inactive` (hidden, history kept) \| `deleted` (soft-deleted). Required on the canonical record and on bulk upload; optional on incremental upserts.
attributes	No	Free-form JSON. Include any fields meaningful to your domain; richer attributes improve recommendation quality.

catalog.csv

item_id,item_type,name,price,category,status
PROD-001,product,Wireless Headphones,149.99,Electronics,active
PROD-002,product,Running Shoes,89.99,Footwear,active
PROD-003,product,Coffee Maker,59.99,Kitchen,active
PROD-004,product,Yoga Mat,29.99,Fitness,inactive

catalog.json

[
  {
    "item_id": "PROD-001",
    "item_type": "product",
    "status": "active",
    "attributes": {
      "name": "Wireless Headphones",
      "price": 149.99,
      "category": "Electronics",
      "brand": "Acoustix"
    }
  },
  {
    "item_id": "PROD-002",
    "item_type": "product",
    "status": "active",
    "attributes": { "name": "Running Shoes", "price": 89.99, "category": "Footwear" }
  }
]

In CSV, columns beyond item_id, item_type, and status are merged into attributes automatically.

User schema

Field	Required	Description
user_id	Yes	Your user identifier. Must match the `user_id` you send in events.
status	Yes	`active` \| `inactive` \| `deleted`. Required on the canonical record and on bulk upload.
created_at	Yes	User signup / first-seen timestamp (ISO 8601).
attributes	No	Free-form JSON. Email, age, geography, interests, anything that helps personalize.

users.csv

user_id,status,created_at,email,age,interests
usr_001,active,2025-01-12T09:00:00Z,alice@example.com,32,"tech,music"
usr_002,active,2025-02-03T14:30:00Z,bob@example.com,45,"sports"
usr_003,active,2025-03-21T08:15:00Z,carol@example.com,28,"books,travel"

Bulk import from the dashboard

Use bulk import for the initial load and any full-catalog refresh. There is no public API for file uploads; the dashboard handles auth, validation, and storage handoff.

Open the dashboard

Drop your file

Drag a CSV or JSON file (max 50 MB) onto the upload area. The dashboard validates the schema before submission and reports any malformed rows up front.

Wait for processing

The file is queued for the recommendation engine's next ingestion cycle (typically a few minutes). The dashboard shows the status of each import.

Imported does not mean live

"Done" in the dashboard means the file is queued. Recommendations reflect new data once the ingestion cycle completes, usually within minutes.

For very large catalogs, split into multiple files and upload sequentially.

Incremental upsert

Use the upsert API when individual records change: a price drops, a product launches, or a user updates their profile. Send only the changed records. Existing fields not in the payload are preserved; attributes is shallow-merged.

Both endpoints require a secret key (lehnz_sk_*). The body can be a single record or an array.

POST/v1/ingest/items/upsert

POST/v1/ingest/users/upsert

curl -X POST https://api.lehnz.com/v1/ingest/items/upsert \
  -H "X-API-KEY: lehnz_sk_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    { "item_id": "PROD-005", "item_type": "product", "status": "active", "attributes": { "name": "New Backpack", "price": 79.99 } },
    { "item_id": "PROD-001", "status": "inactive" }
  ]'

Upserts are queued and applied within seconds. Keep individual requests under 1 MB for predictable latency. For very large incremental loads (10k+ rows), prefer dashboard bulk import.

Lifecycle and status

The status field tells the recommendation engine how to treat a record:

Status	Meaning
`active`	Eligible for recommendations.
`inactive`	Hidden from new recommendations; historical events still resolve for analytics and attribution. Use for out-of-stock SKUs or paused users.
`deleted`	Soft-deleted; excluded everywhere except event-history joins. Use for permanent removals.

On an incremental upsert, status is optional; omitting it on a new record defaults to active.

Unknown status values are rejected

Sending an unrecognized status value (e.g. "archived", "banned") returns 400 Bad Request. Only active, inactive, and deleted are accepted.

Removing an item

Don't delete the row; upsert it with status: "deleted":

curl -X POST https://api.lehnz.com/v1/ingest/items/upsert \
  -H "X-API-KEY: lehnz_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "item_id": "sku-123", "status": "deleted" }'

Upsert the user with status: "deleted". PII is scrubbed from the live state while the user's identity is retained for event-history joins, so existing analytics on past behavior still resolve.

curl -X POST https://api.lehnz.com/v1/ingest/users/upsert \
  -H "X-API-KEY: lehnz_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "user_id": "user-42", "status": "deleted" }'

Errors follow the standard envelope. See Errors & troubleshooting.

Item schema

User schema

Bulk import from the dashboard

Open the dashboard

Drop your file

Wait for processing

Incremental upsert

Lifecycle and status

Removing an item

Deleting a user (GDPR / right to erasure)

Item schema

User schema

Bulk import from the dashboard

Open the dashboard

Drop your file

Wait for processing

Incremental upsert

Lifecycle and status

Removing an item

Deleting a user (GDPR / right to erasure)