> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neuronsearchlab.com/llms.txt
> Use this file to discover all available pages before exploring further.

# NSL Connect

> Resolve first-party identities, manage consent, mint partner-scoped NSL IDs, and run privacy-safe data collaborations.

NSL Connect is the identity and collaboration layer behind NeuronSearchLab recommendations. It helps you keep recommendation behavior consistent across sessions, devices, accounts, and approved partners without exposing NeuronSearchLab's internal identity graph.

You do not need NSL Connect for every recommendation call. If a customer already has one stable first-party `user_id` that is present on every web, app, server, and device request, they can send that ID directly to the recommendation API.

NSL Connect is for the messier cases where recommendation signals are split across anonymous sessions, logged-in accounts, devices, subscriptions, households, consent states, or partner workflows. It turns those identifiers into a consent-aware recommendation identity so ranking behaviour stays consistent without forcing every channel to share the same raw user ID.

Use it when you need to:

* connect pre-login behaviour to the signed-in user once the user authenticates
* link anonymous, session, customer, household, device, CRM, and subscription identifiers into one recommendation identity
* reduce cold starts across web, mobile, CTV, email, and subscription surfaces
* carry consent decisions into recommendation, measurement, activation, and collaboration workflows
* mint partner-scoped NSL IDs that are different for every partner
* run approved data collaborations that return aggregate overlap, not raw partner identity data

## How NSL Connect fits into recommendations

A recommendation engine is only as useful as the signals it can safely connect. NSL Connect gives the platform a stable, consent-aware subject for retrieval, ranking, measurement, and downstream activation.

Without identity resolution, the same person can look like several unrelated users: an anonymous browser session on Monday, a signed-in account on Tuesday, a phone app on Wednesday, and a TV device later in the week. Each surface then starts from partial behaviour.

NSL Connect resolves those identifiers into a canonical `identityId`. Recommendation requests, events, analytics, and collaboration flows can then refer to the same recommendation subject even when the request arrives with a different identifier.

<Steps>
  <Step title="Resolve an identity">
    Send one or more supported identifiers, such as `customer_user_id`, `anonymous_id`, `session_id`, `email_sha256`, `phone_sha256`, `device_id`, `crm_id`, or `subscription_id`.
  </Step>

  <Step title="Attach identifiers to the same subject">
    NSL normalizes and hashes the identifiers, finds existing matches, attaches new identifiers to the canonical `identityId`, and records resolution edges such as login links or same-device links.
  </Step>

  <Step title="Attach consent">
    Record which purposes are allowed for that identity, such as `recommendations`, `personalisation`, `measurement`, `third_party_activation`, or `data_collaboration`.
  </Step>

  <Step title="Serve consistent recommendations">
    Use the resolved `identityId` to retrieve behaviour, profile signals, and recommendation state across surfaces and sessions while respecting restricted purposes.
  </Step>

  <Step title="Collaborate safely when approved">
    Register partners, mint partner-scoped NSL IDs, or create data collaborations only when the required purposes and approvals are present.
  </Step>
</Steps>

## Example: one viewer across web, app, and TV

Imagine a media product with a user who starts anonymous, signs in, and later watches on a connected TV.

<Steps>
  <Step title="Anonymous web visit">
    The user browses articles on the web. The site sends `anonymous_id=anon_123` and `session_id=sess_456`. NSL creates a derived identity and stores early behaviour against it.
  </Step>

  <Step title="Account sign-in">
    The same user signs in later. The backend resolves `customer_user_id=user_789`, `email_sha256=...`, and the existing `anonymous_id=anon_123`. Because the account and email identifiers are strong, NSL attaches the anonymous history to the canonical identity.
  </Step>

  <Step title="Mobile app request">
    The mobile app sends `customer_user_id=user_789` and `app_instance_id=app_abc`. NSL resolves the request to the same `identityId`, so recommendations can use the earlier web reading history instead of treating the app install as a cold start.
  </Step>

  <Step title="Connected TV request">
    The TV app sends `ctv_device_id=ctv_999` plus the signed-in account. NSL links the CTV device to the same subject, so the TV carousel can reflect web and mobile behaviour while still applying TV-specific context, rules, and filters.
  </Step>
</Steps>

The result is consistent behaviour without forcing every channel to use the same raw user ID. A homepage, article rail, app feed, and TV carousel can all resolve to the same recommendation subject, then apply their own context-specific ranking controls.

If consent changes, NSL Connect keeps the identity graph but restricts what the identity can be used for. For example, recommendations may remain allowed while third-party activation or data collaboration is blocked.

## Identity resolution

The identity resolver accepts multiple identifier types and returns a canonical `identityId`, optional `householdId`, match confidence, resolution status, and the purposes that can or cannot be used.

Supported identifier families include:

* customer and account identifiers: `customer_user_id`, `account_id`, `crm_id`, `subscription_id`
* session and anonymous identifiers: `anonymous_id`, `session_id`, `cookie_id`, `app_instance_id`
* privacy-normalized contact identifiers: `email_sha256`, `phone_sha256`
* device and household identifiers: `device_id`, `mobile_ad_id`, `ctv_device_id`, `household_id`
* partner identifiers: `external_partner_id`

Use `POST /api/identity/resolve` when your backend wants NSL to resolve an incoming user, visitor, device, or account before personalization.

## Consent purposes

Consent is purpose-based. NSL Connect tracks allowed and restricted purposes so identity data can be used differently across recommendation, analytics, activation, and collaboration workflows.

Common purposes include:

* `recommendations`
* `personalisation`
* `analytics`
* `identity_resolution`
* `cross_device_linking`
* `measurement`
* `third_party_activation`
* `data_collaboration`

When a purpose is restricted, downstream flows such as partner ID minting or data collaboration are blocked for that identity.

## Partner-scoped NSL IDs

Partner IDs let you register an activation or collaboration partner and mint an NSL ID for a resolved identity. The internal `identityId` never leaves NeuronSearchLab.

Each partner receives its own private key and public encoding. The same internal identity becomes a different NSL ID for every partner, so IDs are not portable across partners unless an approved translation path exists.

Use partner-scoped NSL IDs for:

* privacy-safe activation
* partner-specific measurement
* consent-aware audience handoff
* collaboration workflows where the partner should not receive the internal NSL identity

Minting is consent-gated for `data_collaboration` or `third_party_activation`.

## Data collaborations

Data collaborations let two NSL teams create an approved, purpose-limited match space.

A collaboration has:

* two-party approval before matching is active
* a per-collaboration secret and isolated keyspace
* optional expiry
* revocation that disables matching and purges scoped keys
* supported match identifiers: `email_sha256` and `phone_sha256`
* aggregate overlap calculation only

This is designed for recommendation and measurement use cases where both parties need to understand overlap or eligibility without exchanging raw identity records.

## Recommended workflow

<Steps>
  <Step title="Resolve identities on ingest or request">
    Send identifiers and consent when users interact, sign in, subscribe, or move across devices.
  </Step>

  <Step title="Review identity state in the console">
    Confirm confidence, resolution status, consent purposes, and partner mappings before using the identity for activation or collaboration.
  </Step>

  <Step title="Register partners only when needed">
    Create partner records for approved activation, measurement, or collaboration workflows.
  </Step>

  <Step title="Use collaborations for aggregate overlap">
    Create a collaboration, wait for partner approval, contribute eligible identifiers, then calculate aggregate overlap.
  </Step>
</Steps>

## Related API reference

* [Resolve identity](/api-reference/platform-api/identity/resolveIdentity)
* [Record consent](/api-reference/platform-api/identity/recordConsent)
* [List partners](/api-reference/platform-api/identity/listIdentityPartners)
* [Create partner](/api-reference/platform-api/identity/createIdentityPartner)
* [Mint NSL ID](/api-reference/platform-api/identity/mintNslId)
* [List collaborations](/api-reference/platform-api/identity/listDataCollaborations)
* [Create collaboration](/api-reference/platform-api/identity/createDataCollaboration)
* [Contribute identifiers](/api-reference/platform-api/identity/contributeDataCollaboration)
* [Calculate overlap](/api-reference/platform-api/identity/calculateDataCollaborationOverlap)