Privacy Services API

This guide covers the Privacy Services API integration — enabling partners to enroll members, initiate data broker scans, and submit opt-out requests on behalf of their users.

Online Account Cleaner (OAC) is not currently available for partner integrations. If you have questions about future availability, contact your Gen partner representative.

Detailed configuration, environment-specific base URLs, and credentials are shared separately through secure channels during onboarding.

1. What the Privacy Services Integration Is

Gen provides a set of APIs that allow partners to embed Privacy Search and Privacy Search & Removal features directly within their own product experience — without redirecting users to a Gen-owned property.

At the core of this integration is the Privacy Services API, which handles:

Member enrollment — registering your users into the Privacy system with their personal information.
Data broker scanning — searching people-search and data broker sites for records that match your member's identity.
Opt-out / removal — submitting automated removal requests to data brokers on your member's behalf.

The integration is designed to:

Keep the end-user experience fully within your product.
Allow Gen to manage the complexity of data broker relationships, scan logic, and removal workflows on your behalf.
Give you full control over when scans are initiated and how results are surfaced to your users.

This integration is intended for Gen partners who:

Are building or have built a partner-managed user experience (partner-built UI or embedded Web SDK), and
Are responsible for their own member lifecycle management (enrollment, updates, and removal).

2. Integration Models

All integrations use the Privacy Enrollment API for member onboarding and a Partner Token for authentication. Start by selecting your entitlement model, then choose the UX model that best fits your product experience.

2.1 Entitlement Model

Entitlement Model

How It Works

Entitled

You manage member entitlements via the Entitlement Management API. After a successful entitlement call, you must explicitly call the Privacy Enrollment API to onboard the member into the Privacy system — enrollment is not automatic. Recommended for existing partners who already leverage the Entitlement Management API (PMSS API).

Direct

You integrate directly with the Privacy Services API without a separate entitlement management step. Gen manages entitlements on your behalf.

2.2 UX Model

UX Model

Description

Partner-built

You design and build the full end-user experience using the Privacy Services API.

Embedded Web SDK

Embed the Gen-hosted Privacy Services Web SDK directly into your existing app or SPA.

3. Features & Capabilities

3.1 Available Features

When enrolling a member, you select which Privacy feature(s) to provision:

Feature

What It Provides

PRIVACYSEARCH

Scans data broker sites for records matching your member's identity and returns results for display in your UI.

PRIVACYSEARCHANDREMOVAL

Everything in Privacy Search, plus automated opt-out requests submitted to data brokers on the member's behalf. Required to use the Removal API.

3.2 Configurable Parameters

Features can be customized per partner agreement. Parameters available for configuration include:

Number of data brokers covered
Scan frequency (e.g., every 30 or 90 days)
Scan initiation type (manual or automatic/scheduled)
Removal (opt-out) frequency (e.g., every 30 or 90 days)
Removal initiation type (manual or automatic/scheduled)
White glove agent assistance for cases where automated removal is not possible

Your Gen partner representative will work with you to agree on the right configuration during onboarding.

4. High-Level Architecture & Flow

This section intentionally stays high-level and omits environment-specific base URLs, credentials, and sample tokens. Those details are shared privately during onboarding.

4.1 Overall Flow

Member Enrollment

Your system calls the Privacy Enrollment API with the member's identity information.

Gen returns a memberId that uniquely identifies the member within the Privacy system.

This memberId is required for all subsequent API calls.

Scan

Your system initiates a scan using the memberId.

Gen searches data broker sites for records matching the member's identity.

Your system polls for scan progress and, once complete, retrieves results to display to the member.

If qualifying questions are triggered, your UI presents them to the member to improve result accuracy.

Removal (Opt-Out) (PRIVACYSEARCHANDREMOVAL only)

Your system submits an opt-out request using the memberId.

Gen submits automated removal requests to data brokers in the background.

Your system polls scan results to monitor opt-out progress per broker.

4.2 Member Identification

Partners can identify a member to the Privacy Services API using one of two methods:

Member ID (Entitled integrations) — A unique Gen identifier for the member, used when your integration is Entitled and the member already exists in the Gen ecosystem.
Partner ID + External Member ID (Direct integrations) — Your partner-assigned identifier combined with your own internal member identifier, used for Direct integrations where Gen has no pre-existing member record.

Your Gen partner representative will confirm the correct identification method for your integration model during onboarding.

5. API Reference

The Privacy Services API is organized into three service areas, each with its own base URL. Base URLs for development and production environments are provided by your Gen partner representative.

Service

Base URL

Enrollment

https://{privacyEnrollmentServiceURL}

Scan

https://{privacyScanServiceURL}

Opt-Out / Removal

https://{privacyRemovalServiceURL}

5.1 Required Headers

All API requests must include the following headers:

Header

Description

x-nlok-tenant-id

Your unique Tenant ID, provisioned by Gen during onboarding.

x-nlok-trace-id

A unique UUID generated per request, used for tracing and debugging.

Content-Type

Must be application/json for all POST/PATCH requests.

5.2 Member Enrollment API

Enroll a member POST /enrollment/api/enroll

Registers a member into the Privacy system. Must be completed before initiating a scan.

Key request fields:

Field

Required

Description

memberId or partnerId + externalMemberId

Yes

Member identifier — see Section 4.2.

firstName, lastName

Yes

Member's full name.

primaryEmail

Yes

Member's primary email address.

primaryAddress

Yes

Member's primary address (street, city, state, country, postal code).

plan.features

Yes

Array of feature IDs: PRIVACYSEARCH and/or PRIVACYSEARCHANDREMOVAL.

language

Yes

Language code, e.g., ENG.

countryCode

Yes

ISO country code, e.g., US.

birthYear

Yes

Member's birth year, e.g., 1988.

primaryPhone, secondaryEmails, secondaryPhoneNumbers

Additional contact information to improve scan accuracy.

On success, the API returns a memberId. Store this value — it is required for all subsequent Scan and Opt-Out calls.

Update an enrolled member PATCH /enrollment/api/enroll

Sends only the fields to be updated, along with the member identifier. Use this when a member's address, email, or other profile information changes.

Remove a member To fully remove a member and their data, make two calls in sequence:

DELETE /enrollment/api/enroll — Unenrolls the member and removes their plan.
DELETE /enrollment/api/memberRemoval — Permanently deletes all member data from the system.

5.3 Scan API

Initiate a scan POST /scan-api/scans

Starts a data broker scan for the enrolled member. Pass the memberId and a scanType of ON_DEMAND.

Poll scan progress GET /scan-api/members/{memberId}/scans/poll?onlyProgress=true

Returns the current scan completion percentage (0–100) and a per-broker summary of records found. Poll this endpoint until percentage reaches 100.

Also returns a filterEligible flag — when true, qualifying questions should be presented to the member before retrieving final results (see below).

Submit qualifying questions POST /scan-api/members/{memberId}/scans/filteridentities

When filterEligible is true, present up to 3 questions to the member — 1 address question and up to 2 relative questions. The member responds YES (this profile is mine) or NO (this profile is not mine). This step improves the accuracy of results by filtering out profiles that do not belong to the member.

Retrieve scan results GET /scan-api/members/{memberId}/scans

Returns the full scan results, including per-broker status and individual identity matches. Key response fields include:

Field

Description

scanStatus

Overall scan status: INITIATED, IN_PROGRESS, COMPLETED

optOutStatus

Overall opt-out status: NOT_STARTED, INITIATED, COMPLETED

dataBrokerScanResponses

Array of per-broker results, each with scan status, opt-out status, and matched identities

5.4 Removal API (Opt-Out)

Submit opt-out requests POST /removal/api/members/{memberId}/optouts

Initiates automated opt-out requests to all applicable data brokers for the enrolled member. Requires the PRIVACYSEARCHANDREMOVAL feature and a completed scan.

Returns 201 HTTP Status with no body on success. Opt-out processing then runs in the background automatically.

To monitor progress, poll the Get Scan Results endpoint and check optOutStatus and dbOptOutStatus per broker:

Status

Description

NOT_STARTED

Opt-out not yet requested for this broker.

INITIATED

Opt-out submitted and in progress.

COMPLETED

Opt-out successfully processed.

COULD_NOT_OPTOUT

Automated opt-out was not possible; escalated for manual agent review.

6. Information You'll Need to Provide

To configure and activate your Privacy Services integration, Gen will ask you to provide the following:

6.1 Integration Setup

Integration model selection — Entitled or Direct (see Section 2.1).
UX model selection — Partner-built or Embedded Web SDK (see Section 2.2).
Feature selection — PRIVACYSEARCH and/or PRIVACYSEARCHANDREMOVAL.
Feature configuration preferences — Scan frequency, removal frequency, initiation type, and broker set (see Section 3.2).

6.2 Technical & Security

Client IP address(es) — All IP addresses that will call the Privacy Services API must be allowlisted by Gen before any API calls can be made. Provide these before testing begins.
Technical point of contact — An engineer or architect to work with the Gen team during design, implementation, and testing.
Test member data — Non-production member records for use during integration testing.

All environment-specific base URLs, tenant credentials, and configuration details are exchanged through secure, access-controlled channels and are not included in this external-level guide.

7. Security & Data-Protection Posture

While detailed security policies are documented internally, at a high level:

IP Allowlisting: All client IPs calling the Privacy Services API must be explicitly allowlisted by Gen. This step must be completed before any API calls can be made, including in development environments.
Credential handling: Tenant IDs, trace IDs, base URLs, and any other environment-specific values are treated as non-public and are shared only through secure, access-controlled channels.
Rate limiting: Your integration must handle 429 Too Many Requests responses gracefully, with appropriate retry and backoff logic.
Error handling: Your integration must handle standard 4xx and 5xx HTTP error responses. Specific error codes and payloads for each endpoint are provided in the partner-only technical documentation shared during onboarding.
Member data: Personal information submitted via the Enrollment API is used solely for the purpose of data broker scanning and removal. Partners should apply equivalent controls on their side to protect any member data related to the integration.

8. Onboarding & Next Steps

A typical onboarding sequence looks like:

Alignment on integration model and features

Confirm your entitlement model (Entitled or Direct), UX model, and which Privacy features to provision.

Agree on configurable parameters: scan frequency, removal frequency, broker set, and initiation type.

Security setup

Submit your client IP address(es) for allowlisting.

Your Gen partner representative provisions your Tenant ID and shares environment base URLs through secure channels.

Implementation & testing

Integrate the Enrollment, Scan, and (if applicable) Removal APIs in your development environment.

Validate the full member lifecycle: enroll → scan → poll → qualify → results → opt-out.

Test error handling and retry logic.

Production rollout

Promote your integration to production.

Monitor member enrollment and scan completion rates, and work with your Gen partner representative to tune behavior as needed.

For detailed, environment-specific API specifications, example payloads, and onboarding checklists, your Gen contact will share the appropriate partner-only technical documentation separately.

For questions or to begin onboarding, contact your Gen Digital partner representative.

PreviousIdentity SDK NextSubscription API

Last updated 5 days ago

Was this helpful?