# 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.

{% hint style="warning" %}
Online Account Cleaner (OAC) is not currently available for partner integrations. If you have questions about future availability, contact your Gen partner representative.
{% endhint %}

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

{% stepper %}
{% step %}

## 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.
{% endstep %}

{% step %}

## 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.
{% endstep %}

{% step %}

## 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.
{% endstep %}
{% endstepper %}

### 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` | No       | 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:

1. `DELETE /enrollment/api/enroll` — Unenrolls the member and removes their plan.
2. `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:

{% stepper %}
{% step %}

## 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.
{% endstep %}

{% step %}

## 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.
{% endstep %}

{% step %}

## 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.
{% endstep %}

{% step %}

## 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.
{% endstep %}
{% endstepper %}

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.*


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://even-financial.gitbook.io/developer-center/cyber-safety-and-identity-solutions/privacy-services-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.