Skip to main content
Build a first recommendation flow with the Core API. This walkthrough uses a shell, curl and jq. For a managed client, start with JavaScript, PHP, Next.js or Swift. For a website without backend code, use the no-code start and embed.

1. Prepare your workspace

  1. Create an account.
  2. Open Developers → SDK Credentials, select New Credential, and copy the client ID and secret. The secret is shown once.
  3. Open Relevance → Contexts and copy a context’s integer ID. A new workspace includes a starter context; its name depends on your setup.
  4. Open Data → Events → Configure signals and copy the Click event’s integer ID. Built-in event IDs can be negative; copy the actual value.
Set NSL_CLIENT_ID and NSL_CLIENT_SECRET in your server environment. Keep the secret out of browser code, mobile bundles and source control. Set the IDs you copied:

2. Get an access token

The response’s expires_in tells you how long the token lasts. Reuse it until it needs refreshing. JavaScript, PHP and Next.js clients can handle token exchange and renewal for you. See Authentication.

3. Create two items

Items are the products, articles or other records NSL may recommend. Give each one a useful description and a stable source identifier so repeating this example updates the same records.
NSL assigns each item an integer ID. Store those IDs alongside your own records for future updates and events. Check both items in Data → Items. For a full catalogue, see Catalogue.

4. Request a recommendation list

Use an application-owned test user ID. Keep it consistent when recording that user’s events.
The response contains ranked records in data and a request_id. Each record identifies its item with item_id. With a tiny catalogue and no user history, this validates connectivity and retrieval; it does not demonstrate learned personalisation yet. If data is empty, check that the items are active and that your context’s filters permit them. Troubleshooting covers authentication, empty results and missing events.

5. Record a test click

Copy the first returned item and the request ID directly from the response. This keeps the interaction tied to the list that produced it.
Open Data → Events to confirm the test click arrived. In Insights → Explainability, enter the request_id to inspect the served decision. Keep test traffic separate from real customer identities.

Build the production flow

Your application repeats the same loop: keep the catalogue current, fetch a list for a user and context, render it, then send actual engagement with that list’s request ID.

Key concepts

Understand contexts, events, pipelines, rules and models.

Track events

Choose event types and preserve attribution across placements.

Serve recommendations

Add similar-item rails and several placements on a page.

Launch a placement

Configure, verify and roll out a production context.