Managing personal data in Master Data v2

Master Data v2 allows you to declare which fields in a data entity contain personal data. Once configured, these fields are encrypted, stored with data residency controls, and automatically participate in data subject request flows (e.g., right to be forgotten). When retrieved, personal data fields are masked by default, and you must explicitly request unmasked access.

This guide covers the full integration flow: configuring personal data fields, saving documents, reading them, and searching.

This feature is only available for Master Data v2 entities. Master Data v1 entities (e.g., CL, AD) are not supported.

You must have an existing Master Data v2 data entity. If you need to create one, use the Save schema by name endpoint.

Personal data configuration is set at the data entity level, not within individual schemas. This avoids conflicts when multiple schemas coexist for the same entity.

Every document containing personal data must be linked to a data subject, the individual who owns the data. You define this association by mapping a field (e.g., email) as the data subject identifier (SubjectIdField).

Use the Configure personal data fields endpoint to declare which fields contain personal data and which field identifies the data subject.

To inspect the current personal data configuration for an entity before changing it, use the Get personal data configuration endpoint. We recommend inspecting first, because saving a new configuration locks the endpoint for up to 12 hours (see What happens after configuration).

Saving a new configuration triggers a background process that re-tokenizes all existing documents in the entity. While this process runs, the Configure personal data fields endpoint is locked for the affected entity for up to 12 hours and returns 423 Locked to prevent concurrent reprocessing jobs.

Use the standard document creation and update endpoints to save documents with personal data:

• Create new document
• Create document with custom ID or update entire document
• Update partial document

Master Data v2 automatically checks the personal data configuration for the entity. The values of personal data fields (email and firstName in this example) are stored separately with encryption and special data residency, while non-personal fields (categories) are stored normally.

Every document saved in an entity with personal data configuration must include the field declared in SubjectIdField.

Use the standard document retrieval endpoints to read documents:

• Get document
• Search documents
• Scroll documents

By default, personal data fields are returned with masked values:

Personal data fields are returned with characters replaced by asterisks. Non-personal fields are returned normally. The exact mask pattern shown above is illustrative and may vary by field type.

To retrieve the original values of personal data fields, add _unmasked=true to the query string:

The _unmasked parameter also applies to Search documents and Scroll documents.

Personal data fields can be used as search filters, with two requirements. Like any other searchable field, they must be added to the schema's v-indexed array. Unlike other fields, they only support exact matching.

Add the personal data field to the v-indexed array in the schema, the same way you would index any other searchable field:

The response follows the same masking rules. Personal data fields are masked by default. To retrieve unmasked values, add _unmasked=true.

Only exact match filters are supported for personal data fields. Range filters, partial matches, and full-text search on these fields are not supported.

Keep the following restrictions in mind when working with personal data in Master Data v2:

• Master Data v1: Not supported. Only v2 entities are compatible.
• Search operators: Personal data fields only support exact match. Range, contains, and full-text operators are not available.
• All-or-nothing unmasking: You can't unmask individual fields. The _unmasked parameter applies to all personal data fields in the document.
• Data subject ID required: Every document in an entity with personal data must include the field configured in SubjectIdField.