From 79a7f62e7092702f62b76c89e582c3a4e0df4e80 Mon Sep 17 00:00:00 2001 From: Pedro Antunes <47991446+PedroAntunesCosta@users.noreply.github.com> Date: Wed, 8 Apr 2026 18:28:56 -0300 Subject: [PATCH 1/8] docs: document pii masking and unmasked retrieval --- VTEX - Master Data API - v2.json | 66 +++++++++++++++++++++++++++++--- 1 file changed, 60 insertions(+), 6 deletions(-) diff --git a/VTEX - Master Data API - v2.json b/VTEX - Master Data API - v2.json index 669c9dfa8..fe3f81c4c 100644 --- a/VTEX - Master Data API - v2.json +++ b/VTEX - Master Data API - v2.json @@ -165,7 +165,7 @@ "Documents" ], "summary": "Get document", - "description": "Retrieves a document by ID.\n\r\n\r>ℹ️ Assign the `_fields` parameter in the query string to retrieve the desired fields. If you want to return all the fields use `_fields=_all`.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", + "description": "Retrieves a document by ID.\n\r\n\r>ℹ️ Assign the `_fields` parameter in the query string to retrieve the desired fields. If you want to return all the fields use `_fields=_all`.\r\n\r\n>ℹ️ Fields flagged as PII (`v-pii`) in the data entity schema are returned with masked values by default. To retrieve the original values, add the `unmasked=true` query parameter.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Getdocument", "parameters": [ { @@ -185,6 +185,9 @@ }, { "$ref": "#/components/parameters/_schema" + }, + { + "$ref": "#/components/parameters/unmasked" } ], "responses": { @@ -353,7 +356,7 @@ "Search" ], "summary": "Search documents", - "description": "Retrieves Master Data v2 documents' information, while choosing which fields will be returned and filtering documents by specific fields.\r\n\r\n> The response header `REST-Content-Range` indicates the total amount of results for that specific search. For example, it may return `resources 0-100/136108`, which indicates it has returned the first 100 results out of a total of 136108.\r\n\r\nBelow you can see some query examples and learn more about each query parameter.\n\r\n\rLearn more about [Pagination in the Master Data API](https://developers.vtex.com/docs/guides/pagination-in-the-master-data-api).\r\n\r\n>⚠️ Avoid sending too many requests with wildcards (`*`) in the search parameters or that use the `keyword` parameter. This may lead to this endpoint being temporarily blocked for your account. If this happens you will receive an error with status code `503`.\r\n\r\n## Query examples\r\n\r\n| **Query Type** | **Example** |\r\n|-|-|\r\n| **Simple filter** | `\/dataentities\/Newsletter\/search?email=my@email.com` |\r\n| **Complex filter** | `\/dataentities\/Newsletter\/search?_where=(firstName=Jon OR lastName=Smith) OR (createdIn between 2001-01-01 AND 2016-01-01)` |\r\n| **Date range** | `\/dataentities\/Newsletter\/search?_where=createdIn between 2001-01-01 AND 2016-01-01` |\r\n| **Range numeric fields** | `\/dataentities\/Newsletter\/search?_where=age between 18 AND 25` |\r\n| **Partial filter** | `\/dataentities\/Newsletter\/search?firstName=*Maria*` |\r\n| **Filter for null values** | `\/dataentities\/Newsletter\/search?_where=firstName is null` |\r\n| **Filter for non-null values** | `\/dataentities\/Newsletter\/search?_where=firstName is not null` |\r\n| **Filter for difference** | `\/dataentities\/Newsletter\/search?_where=firstName<>maria` |\r\n| **Filter greater than** | `\/dataentities\/Newsletter\/search?_where=number>5` |\r\n| **Filter less than** | `\/dataentities\/Newsletter\/search?_where=date<2001-01-01` |\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", + "description": "Retrieves Master Data v2 documents' information, while choosing which fields will be returned and filtering documents by specific fields.\r\n\r\n> The response header `REST-Content-Range` indicates the total amount of results for that specific search. For example, it may return `resources 0-100/136108`, which indicates it has returned the first 100 results out of a total of 136108.\r\n\r\nBelow you can see some query examples and learn more about each query parameter.\n\r\n\rLearn more about [Pagination in the Master Data API](https://developers.vtex.com/docs/guides/pagination-in-the-master-data-api).\r\n\r\n>ℹ️ Fields flagged as PII (`v-pii`) in the data entity schema are returned with masked values by default. To retrieve the original values, add the `unmasked=true` query parameter.\r\n\r\n>⚠️ Avoid sending too many requests with wildcards (`*`) in the search parameters or that use the `keyword` parameter. This may lead to this endpoint being temporarily blocked for your account. If this happens you will receive an error with status code `503`.\r\n\r\n## Query examples\r\n\r\n| **Query Type** | **Example** |\r\n|-|-|\r\n| **Simple filter** | `\/dataentities\/Newsletter\/search?email=my@email.com` |\r\n| **Complex filter** | `\/dataentities\/Newsletter\/search?_where=(firstName=Jon OR lastName=Smith) OR (createdIn between 2001-01-01 AND 2016-01-01)` |\r\n| **Date range** | `\/dataentities\/Newsletter\/search?_where=createdIn between 2001-01-01 AND 2016-01-01` |\r\n| **Range numeric fields** | `\/dataentities\/Newsletter\/search?_where=age between 18 AND 25` |\r\n| **Partial filter** | `\/dataentities\/Newsletter\/search?firstName=*Maria*` |\r\n| **Filter for null values** | `\/dataentities\/Newsletter\/search?_where=firstName is null` |\r\n| **Filter for non-null values** | `\/dataentities\/Newsletter\/search?_where=firstName is not null` |\r\n| **Filter for difference** | `\/dataentities\/Newsletter\/search?_where=firstName<>maria` |\r\n| **Filter greater than** | `\/dataentities\/Newsletter\/search?_where=number>5` |\r\n| **Filter less than** | `\/dataentities\/Newsletter\/search?_where=date<2001-01-01` |\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Searchdocuments", "parameters": [ { @@ -379,6 +382,9 @@ }, { "$ref": "#/components/parameters/_sort" + }, + { + "$ref": "#/components/parameters/unmasked" } ], "responses": { @@ -466,7 +472,7 @@ "Scroll" ], "summary": "Scroll documents", - "description": "Returns a list of documents according to query parameter filters. If you need to query the entire database, or your collection is over 10000 documents, use this endpoint.\r\n\r\nIn the first request, the `X-VTEX-MD-TOKEN` token will be obtained in the response header. This token must be passed to the next request in the `_token` query string parameter. The token expires after 20 minutes of inactivity, and each request made with the token during this time resets the expiration timer.\r\n\r\nAfter the token is obtained, it is no longer necessary to send the filter or document size per page parameters. You only need to resend the token until the document collection is empty.\r\n\r\nFirst request:\r\n```\r\n/dataentities/Newsletter/scroll?isCluster=true&_size=250&_fields=email,firstName\r\n```\r\n\r\nRetrieve the token in the header `X-VTEX-MD-TOKEN` from the first request's response and use it to make the following requests.\r\n\r\nSubsequent requests:\r\n```\r\n/dataentities/Newsletter/scroll?_token={tokenValue}\r\n```\n\r\n\rLearn more about [Pagination in the Master Data API](https://developers.vtex.com/docs/guides/pagination-in-the-master-data-api).\r\n\r\n>⚠️ Avoid sending too many requests with wildcards (`*`) in the search parameters or using the `keyword` parameter. This may lead to this endpoint being temporarily blocked for your account. If this happens you will receive an error with status code `429`.\r\n\r\n## Query examples\r\n\r\n| **Query Type** | **Example** |\r\n|-|-|\r\n| **Simple filter** | `\/dataentities\/Newsletter\/scroll?email=my@email.com` |\r\n| **Complex filter** | `\/dataentities\/Newsletter\/scroll?_where=(firstName=Jon OR lastName=Smith) OR (createdIn between 2001-01-01 AND 2016-01-01)` |\r\n| **Date range** | `\/dataentities\/Newsletter\/scroll?_where=createdIn between 2001-01-01 AND 2016-01-01` |\r\n| **Range numeric fields** | `\/dataentities\/Newsletter\/scroll?_where=age between 18 AND 25` |\r\n| **Partial filter** | `\/dataentities\/Newsletter\/scroll?firstName=*Maria*` |\r\n| **Filter for null values** | `\/dataentities\/Newsletter\/scroll?_where=firstName is null` |\r\n| **Filter for non-null values** | `\/dataentities\/Newsletter\/scroll?_where=firstName is not null` |\r\n| **Filter for difference** | `\/dataentities\/Newsletter\/scroll?_where=firstName<>maria` |\r\n| **Filter greater than** | `\/dataentities\/Newsletter\/scroll?_where=number>5` |\r\n| **Filter less than** | `\/dataentities\/Newsletter\/scroll?_where=date<2001-01-01` |\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", + "description": "Returns a list of documents according to query parameter filters. If you need to query the entire database, or your collection is over 10000 documents, use this endpoint.\r\n\r\nIn the first request, the `X-VTEX-MD-TOKEN` token will be obtained in the response header. This token must be passed to the next request in the `_token` query string parameter. The token expires after 20 minutes of inactivity, and each request made with the token during this time resets the expiration timer.\r\n\r\nAfter the token is obtained, it is no longer necessary to send the filter or document size per page parameters. You only need to resend the token until the document collection is empty.\r\n\r\nFirst request:\r\n```\r\n/dataentities/Newsletter/scroll?isCluster=true&_size=250&_fields=email,firstName\r\n```\r\n\r\nRetrieve the token in the header `X-VTEX-MD-TOKEN` from the first request's response and use it to make the following requests.\r\n\r\nSubsequent requests:\r\n```\r\n/dataentities/Newsletter/scroll?_token={tokenValue}\r\n```\n\r\n\rLearn more about [Pagination in the Master Data API](https://developers.vtex.com/docs/guides/pagination-in-the-master-data-api).\r\n\r\n>ℹ️ Fields flagged as PII (`v-pii`) in the data entity schema are returned with masked values by default. To retrieve the original values, add the `unmasked=true` query parameter.\r\n\r\n>⚠️ Avoid sending too many requests with wildcards (`*`) in the search parameters or using the `keyword` parameter. This may lead to this endpoint being temporarily blocked for your account. If this happens you will receive an error with status code `429`.\r\n\r\n## Query examples\r\n\r\n| **Query Type** | **Example** |\r\n|-|-|\r\n| **Simple filter** | `\/dataentities\/Newsletter\/scroll?email=my@email.com` |\r\n| **Complex filter** | `\/dataentities\/Newsletter\/scroll?_where=(firstName=Jon OR lastName=Smith) OR (createdIn between 2001-01-01 AND 2016-01-01)` |\r\n| **Date range** | `\/dataentities\/Newsletter\/scroll?_where=createdIn between 2001-01-01 AND 2016-01-01` |\r\n| **Range numeric fields** | `\/dataentities\/Newsletter\/scroll?_where=age between 18 AND 25` |\r\n| **Partial filter** | `\/dataentities\/Newsletter\/scroll?firstName=*Maria*` |\r\n| **Filter for null values** | `\/dataentities\/Newsletter\/scroll?_where=firstName is null` |\r\n| **Filter for non-null values** | `\/dataentities\/Newsletter\/scroll?_where=firstName is not null` |\r\n| **Filter for difference** | `\/dataentities\/Newsletter\/scroll?_where=firstName<>maria` |\r\n| **Filter greater than** | `\/dataentities\/Newsletter\/scroll?_where=number>5` |\r\n| **Filter less than** | `\/dataentities\/Newsletter\/scroll?_where=date<2001-01-01` |\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Scrolldocuments", "parameters": [ { @@ -495,6 +501,9 @@ }, { "$ref": "#/components/parameters/_sort" + }, + { + "$ref": "#/components/parameters/unmasked" } ], "responses": { @@ -653,7 +662,7 @@ "Schemas" ], "summary": "Save schema by name", - "description": "Creates or edits a data entity schema. Learn more about [Master Data schemas](https://developers.vtex.com/vtex-rest-api/docs/master-data-schema-lifecycle).\r\n\r\n> Note that if you send a `schemaName` that does not exist for that data entity, this request will create it.\r\n\r\nThis request can also be used to [create or edit Master Data v2 triggers](https://developers.vtex.com/vtex-rest-api/docs/setting-up-triggers-in-master-data-v2).\r\n\r\n> Each Master Data v2 data entity can have up to 60 schemas.\r\n\r\n## Indexing fields for search, scroll and sort\r\n\r\nTo filter or sort by a field in [Search documents](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/search) or [Scroll documents](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/scroll), add that field to the `v-indexed` array in the schema. This is the schema-level index (separate from the [indices](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/indices) endpoint).\r\n\r\n- `v-indexed`: Array of property names that Master Data v2 must index for `/search`, `/scroll`, and `_sort`. Use it whenever you want to use `_where`, `_sort`, or range filters (e.g. `_where=postalCode between 10000 AND 20000`) on that field. Indexing runs asynchronously after the schema is saved.\r\n- `filterable` and `searchable`: Apply to the UI (e.g. Master Data v1/CRM-style behavior). They do **not** create the index used by `/search`; only `v-indexed` does.\r\n\r\n**Example request body with `v-indexed`:**\r\n\r\n```json\r\n{\r\n \"properties\": {\r\n \"skuId\": { \"type\": \"string\" },\r\n \"postalCode\": { \"type\": \"string\" }\r\n },\r\n \"v-indexed\": [\"postalCode\"]\r\n}\r\n```\r\n\r\n> ℹ️ Use `v-indexed` when you need fields to be filterable/sortable in `/search`. Use the [/indices](https://developers.vtex.com/docs/api-reference/master-data-api-v2#put-/api/dataentities/-dataEntityName-/indices) endpoint when you need entity-level uniqueness, composite keys, or relationships between entities.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", + "description": "Creates or edits a data entity schema. Learn more about [Master Data schemas](https://developers.vtex.com/vtex-rest-api/docs/master-data-schema-lifecycle).\r\n\r\n> Note that if you send a `schemaName` that does not exist for that data entity, this request will create it.\r\n\r\nThis request can also be used to [create or edit Master Data v2 triggers](https://developers.vtex.com/vtex-rest-api/docs/setting-up-triggers-in-master-data-v2).\r\n\r\n> Each Master Data v2 data entity can have up to 60 schemas.\r\n\r\n## Indexing fields for search, scroll and sort\r\n\r\nTo filter or sort by a field in [Search documents](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/search) or [Scroll documents](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/scroll), add that field to the `v-indexed` array in the schema. This is the schema-level index (separate from the [indices](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/indices) endpoint).\r\n\r\n- `v-indexed`: Array of property names that Master Data v2 must index for `/search`, `/scroll`, and `_sort`. Use it whenever you want to use `_where`, `_sort`, or range filters (e.g. `_where=postalCode between 10000 AND 20000`) on that field. Indexing runs asynchronously after the schema is saved.\r\n- `filterable` and `searchable`: Apply to the UI (e.g. Master Data v1/CRM-style behavior). They do **not** create the index used by `/search`; only `v-indexed` does.\r\n\r\n**Example request body with `v-indexed`:**\r\n\r\n```json\r\n{\r\n \"properties\": {\r\n \"skuId\": { \"type\": \"string\" },\r\n \"postalCode\": { \"type\": \"string\" }\r\n },\r\n \"v-indexed\": [\"postalCode\"]\r\n}\r\n```\r\n\r\n> ℹ️ Use `v-indexed` when you need fields to be filterable/sortable in `/search`. Use the [/indices](https://developers.vtex.com/docs/api-reference/master-data-api-v2#put-/api/dataentities/-dataEntityName-/indices) endpoint when you need entity-level uniqueness, composite keys, or relationships between entities.\r\n\r\n## Flagging fields as PII\r\n\r\nTo flag fields that contain personally identifiable information (PII), add those field names to the `v-pii` array in the schema. Fields listed in `v-pii` are handled according to data protection best practices: their values are stored securely and returned masked by default when retrieving documents.\r\n\r\nTo retrieve the original (unmasked) values of PII fields, pass the query parameter `unmasked=true` in [Get document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/documents/-id-), [Search documents](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/search), or [Scroll documents](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/scroll).\r\n\r\n**Example request body with `v-pii`:**\r\n\r\n```json\r\n{\r\n \"properties\": {\r\n \"email\": { \"type\": \"string\" },\r\n \"firstName\": { \"type\": \"string\" },\r\n \"document\": { \"type\": \"string\" }\r\n },\r\n \"v-pii\": [\"email\", \"document\"]\r\n}\r\n```\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Saveschemabyname", "parameters": [ { @@ -664,7 +673,7 @@ } ], "requestBody": { - "description": "JSON Schema of the data entity. Include `v-indexed` with an array of property names when you will filter or sort by those fields in /search or /scroll.", + "description": "JSON Schema of the data entity. Include `v-indexed` with an array of property names when you will filter or sort by those fields in /search or /scroll. Include `v-pii` with an array of property names to flag fields as personally identifiable information (PII), which will be masked by default on retrieval.", "content": { "application/json": { "schema": { @@ -696,6 +705,26 @@ "postalCode" ] } + }, + "withVPii": { + "summary": "Schema with v-pii for PII masking", + "value": { + "properties": { + "email": { + "type": "string" + }, + "firstName": { + "type": "string" + }, + "document": { + "type": "string" + } + }, + "v-pii": [ + "email", + "document" + ] + } } } } @@ -1275,7 +1304,7 @@ "properties" ], "type": "object", - "description": "JSON Schema of the data entity. Add `v-indexed` with an array of property names to make those fields filterable and sortable in /search and /scroll.", + "description": "JSON Schema of the data entity. Add `v-indexed` with an array of property names to make those fields filterable and sortable in /search and /scroll. Add `v-pii` with an array of property names to flag fields as PII, which will be masked by default on retrieval.", "properties": { "properties": { "type": "object", @@ -1310,6 +1339,13 @@ "type": "string" }, "description": "Names of properties to index for /search, /scroll, and _sort. Required for reliable filtering (e.g. _where=field=value) and sorting (_sort=field ASC). Indexing is asynchronous after schema save." + }, + "v-pii": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Names of properties that contain personally identifiable information (PII). Fields listed here are handled according to data protection best practices and returned with masked values by default. To retrieve original values, use the `unmasked=true` query parameter on document retrieval endpoints." } } }, @@ -1356,6 +1392,13 @@ } } } + }, + "v-pii": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Names of properties flagged as personally identifiable information (PII)." } } } @@ -1761,6 +1804,17 @@ "type": "integer", "default": 100 } + }, + "unmasked": { + "name": "unmasked", + "in": "query", + "description": "When set to `true`, fields flagged as PII (`v-pii`) in the data entity schema are returned with their original values. By default (`false`), PII fields are returned with masked values.", + "required": false, + "style": "form", + "schema": { + "type": "boolean", + "default": false + } } } }, From 948e736c445dd98bee6723c75b7475d9cb4966d2 Mon Sep 17 00:00:00 2001 From: PedroAntunesCosta <> Date: Wed, 8 Apr 2026 21:32:58 +0000 Subject: [PATCH 2/8] chore: update postman files --- .../VTEX - Master Data API - v2.json | 335 +++++++++++++----- 1 file changed, 248 insertions(+), 87 deletions(-) diff --git a/PostmanCollections/VTEX - Master Data API - v2.json b/PostmanCollections/VTEX - Master Data API - v2.json index 4609dee2b..f9d3b2650 100644 --- a/PostmanCollections/VTEX - Master Data API - v2.json +++ b/PostmanCollections/VTEX - Master Data API - v2.json @@ -1,10 +1,10 @@ { "_": { - "postman_id": "688a451e-ed75-4f71-b0ac-efa28cfdee37" + "postman_id": "c5e2ef5c-1f65-490e-b9a4-4f1c0d67ecdf" }, "item": [ { - "id": "d85e9d3e-6057-4a24-9c17-8dcb01a46c17", + "id": "f5661f20-3027-4cb5-aed8-a60e8f7cd14d", "name": "Documents", "description": { "content": "", @@ -12,7 +12,7 @@ }, "item": [ { - "id": "e0dd5389-4d71-4b50-9a10-7d4c533675d4", + "id": "3b9a864e-7b88-434b-875c-d6584ce33e4e", "name": "Create new document", "request": { "name": "Create new document", @@ -99,7 +99,7 @@ "_": { "postman_previewlanguage": "json" }, - "id": "c7724b34-1468-4563-86a4-3c6e2acda7d3", + "id": "99414739-b64a-4773-9361-d1d59e6b703d", "name": "Created", "originalRequest": { "url": { @@ -188,7 +188,7 @@ "_": { "postman_previewlanguage": "json" }, - "id": "c6d53539-2a8e-4c69-afef-08b088b2fe41", + "id": "eddaee1f-505f-445b-8dab-61eaa9ee7fe3", "name": "Accepted\n\nThe document creation has been accepted and will be processed asynchronously due to background operations.", "originalRequest": { "url": { @@ -278,7 +278,7 @@ { "listen": "test", "script": { - "id": "c3a2b58f-00ab-497c-9d0b-61eab3b8bbba", + "id": "7231e2e9-a98d-4ea4-8572-ad097719454a", "type": "text/javascript", "exec": [ "// Validate status 2xx \npm.test(\"[POST]::/api/dataentities/:dataEntityName/documents - Status code is 2xx\", function () {\n pm.response.to.be.success;\n});\n", @@ -294,7 +294,7 @@ } }, { - "id": "49b3b6cf-49e2-4ad1-bafc-e9e747704bb1", + "id": "0e6b5908-a7dd-4d0e-8a91-5e8d5a7a2886", "name": "Create partial document", "request": { "name": "Create partial document", @@ -381,7 +381,7 @@ "_": { "postman_previewlanguage": "json" }, - "id": "3b7b27d8-e1d4-49e0-a087-cbd1e9bb3657", + "id": "d8a8b0b2-e2a2-46ca-bd16-1381500103f1", "name": "OK", "originalRequest": { "url": { @@ -471,7 +471,7 @@ { "listen": "test", "script": { - "id": "46aa3dc3-9b1e-4e35-8dd7-3e7460ab0f51", + "id": "c173f44f-4d85-41e1-97cd-249736f1ab74", "type": "text/javascript", "exec": [ "// Validate status 2xx \npm.test(\"[PATCH]::/api/dataentities/:dataEntityName/documents - Status code is 2xx\", function () {\n pm.response.to.be.success;\n});\n", @@ -487,12 +487,12 @@ } }, { - "id": "a27a0903-7fe9-4eb1-bda0-fb2b865a8035", + "id": "2c17f3e3-2501-4054-9df0-92c5c4ff0b0e", "name": "Get document", "request": { "name": "Get document", "description": { - "content": "Retrieves a document by ID.\n\r\n\r>ℹ️ Assign the `_fields` parameter in the query string to retrieve the desired fields. If you want to return all the fields use `_fields=_all`.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", + "content": "Retrieves a document by ID.\n\r\n\r>ℹ️ Assign the `_fields` parameter in the query string to retrieve the desired fields. If you want to return all the fields use `_fields=_all`.\r\n\r\n>ℹ️ Fields flagged as PII (`v-pii`) in the data entity schema are returned with masked values by default. To retrieve the original values, add the `unmasked=true` query parameter.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "type": "text/plain" }, "url": { @@ -524,6 +524,15 @@ }, "key": "_schema", "value": "schema" + }, + { + "disabled": true, + "description": { + "content": "When set to `true`, fields flagged as PII (`v-pii`) in the data entity schema are returned with their original values. By default (`false`), PII fields are returned with masked values.", + "type": "text/plain" + }, + "key": "unmasked", + "value": "false" } ], "variable": [ @@ -581,7 +590,7 @@ "_": { "postman_previewlanguage": "json" }, - "id": "9034bfaa-07f6-4e75-9c6a-6433df76bda5", + "id": "65710b49-1a01-4894-ae62-1f884dcecbf2", "name": "OK", "originalRequest": { "url": { @@ -613,6 +622,15 @@ }, "key": "_schema", "value": "schema" + }, + { + "disabled": true, + "description": { + "content": "When set to `true`, fields flagged as PII (`v-pii`) in the data entity schema are returned with their original values. By default (`false`), PII fields are returned with masked values.", + "type": "text/plain" + }, + "key": "unmasked", + "value": "false" } ], "variable": [] @@ -668,7 +686,7 @@ { "listen": "test", "script": { - "id": "bd9a8270-35fa-4207-9fb5-0c4a538387a2", + "id": "9a417046-4003-4e7c-89f4-51a861c7cbd2", "type": "text/javascript", "exec": [ "// Validate status 2xx \npm.test(\"[GET]::/api/dataentities/:dataEntityName/documents/:id - Status code is 2xx\", function () {\n pm.response.to.be.success;\n});\n", @@ -684,7 +702,7 @@ } }, { - "id": "8b959149-5893-414d-ad98-b1447e465ded", + "id": "9da27e44-1057-423c-b762-b5b60dcb42a0", "name": "Create document with custom ID or update entire document", "request": { "name": "Create document with custom ID or update entire document", @@ -778,7 +796,7 @@ "_": { "postman_previewlanguage": "text" }, - "id": "1d491cf6-a1ea-46be-97c4-1a87dc8e2451", + "id": "8e279550-589b-4f63-8ebf-e8c0605425ac", "name": "No Content", "originalRequest": { "url": { @@ -858,7 +876,7 @@ "_": { "postman_previewlanguage": "text" }, - "id": "21db2259-b343-4bb6-aa4d-3e22968a6cf6", + "id": "9ad158fc-5b49-43d7-b341-1712d11bb0bb", "name": "Bad Request\n\nInvalid information in JSON.", "originalRequest": { "url": { @@ -938,7 +956,7 @@ "_": { "postman_previewlanguage": "text" }, - "id": "c329ef40-4d12-4f9d-b4ff-f66b8b61a993", + "id": "231b421b-ea2b-4343-bfbf-0cb6ac8a0c53", "name": "Forbidden\n\nUnauthorized access.", "originalRequest": { "url": { @@ -1019,7 +1037,7 @@ { "listen": "test", "script": { - "id": "d8f88634-7772-489b-b913-e3a20323eb07", + "id": "067e7ebe-9b66-4c75-a263-fba34c8f5cd7", "type": "text/javascript", "exec": [ "// Validate status 2xx \npm.test(\"[PUT]::/api/dataentities/:dataEntityName/documents/:id - Status code is 2xx\", function () {\n pm.response.to.be.success;\n});\n", @@ -1033,7 +1051,7 @@ } }, { - "id": "cb3daef6-eafb-4ae1-a445-149caa6c8565", + "id": "0e8d0b65-6cfb-4562-9bd4-9baa6557eadf", "name": "Update partial document", "request": { "name": "Update partial document", @@ -1127,7 +1145,7 @@ "_": { "postman_previewlanguage": "text" }, - "id": "a8ad3134-e491-4ecd-bb6d-6793bcb4cf3f", + "id": "18c84c59-9d56-44aa-bb48-dfb7e7073f1e", "name": "No Content", "originalRequest": { "url": { @@ -1208,7 +1226,7 @@ { "listen": "test", "script": { - "id": "d5871bc5-01ff-4e14-9a36-12e652ef68e6", + "id": "21cc7d40-491f-4b94-a98b-826c7ef3dcfe", "type": "text/javascript", "exec": [ "// Validate status 2xx \npm.test(\"[PATCH]::/api/dataentities/:dataEntityName/documents/:id - Status code is 2xx\", function () {\n pm.response.to.be.success;\n});\n", @@ -1222,7 +1240,7 @@ } }, { - "id": "fe486016-f217-410e-aa8b-56a93f5c7829", + "id": "87558264-7312-4152-87f4-a723749813cd", "name": "Delete document", "request": { "name": "Delete document", @@ -1293,7 +1311,7 @@ "_": { "postman_previewlanguage": "text" }, - "id": "ea05fbd0-5cea-44ad-82ec-1c37dd9c3778", + "id": "32ca4b7e-18eb-492e-9310-95ad157298a7", "name": "No Content", "originalRequest": { "url": { @@ -1351,7 +1369,7 @@ { "listen": "test", "script": { - "id": "47227d61-e318-46a4-8342-960338064a46", + "id": "bcde99c1-eb06-42aa-8130-d64d873cd606", "type": "text/javascript", "exec": [ "// Validate status 2xx \npm.test(\"[DELETE]::/api/dataentities/:dataEntityName/documents/:id - Status code is 2xx\", function () {\n pm.response.to.be.success;\n});\n", @@ -1368,7 +1386,7 @@ "event": [] }, { - "id": "28125def-c697-420b-8a00-983bb207eb73", + "id": "78de0071-2101-47c1-a42a-941d593fcd89", "name": "Search", "description": { "content": "", @@ -1376,12 +1394,12 @@ }, "item": [ { - "id": "49df9006-dc40-4a00-9f16-c4ff8debba34", + "id": "de148ed1-b95f-4984-a635-df5ea18bb2a1", "name": "Search documents", "request": { "name": "Search documents", "description": { - "content": "Retrieves Master Data v2 documents' information, while choosing which fields will be returned and filtering documents by specific fields.\r\n\r\n> The response header `REST-Content-Range` indicates the total amount of results for that specific search. For example, it may return `resources 0-100/136108`, which indicates it has returned the first 100 results out of a total of 136108.\r\n\r\nBelow you can see some query examples and learn more about each query parameter.\n\r\n\rLearn more about [Pagination in the Master Data API](https://developers.vtex.com/docs/guides/pagination-in-the-master-data-api).\r\n\r\n>⚠️ Avoid sending too many requests with wildcards (`*`) in the search parameters or that use the `keyword` parameter. This may lead to this endpoint being temporarily blocked for your account. If this happens you will receive an error with status code `503`.\r\n\r\n## Query examples\r\n\r\n| **Query Type** | **Example** |\r\n|-|-|\r\n| **Simple filter** | `/dataentities/Newsletter/search?email=my@email.com` |\r\n| **Complex filter** | `/dataentities/Newsletter/search?_where=(firstName=Jon OR lastName=Smith) OR (createdIn between 2001-01-01 AND 2016-01-01)` |\r\n| **Date range** | `/dataentities/Newsletter/search?_where=createdIn between 2001-01-01 AND 2016-01-01` |\r\n| **Range numeric fields** | `/dataentities/Newsletter/search?_where=age between 18 AND 25` |\r\n| **Partial filter** | `/dataentities/Newsletter/search?firstName=*Maria*` |\r\n| **Filter for null values** | `/dataentities/Newsletter/search?_where=firstName is null` |\r\n| **Filter for non-null values** | `/dataentities/Newsletter/search?_where=firstName is not null` |\r\n| **Filter for difference** | `/dataentities/Newsletter/search?_where=firstName<>maria` |\r\n| **Filter greater than** | `/dataentities/Newsletter/search?_where=number>5` |\r\n| **Filter less than** | `/dataentities/Newsletter/search?_where=date<2001-01-01` |\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", + "content": "Retrieves Master Data v2 documents' information, while choosing which fields will be returned and filtering documents by specific fields.\r\n\r\n> The response header `REST-Content-Range` indicates the total amount of results for that specific search. For example, it may return `resources 0-100/136108`, which indicates it has returned the first 100 results out of a total of 136108.\r\n\r\nBelow you can see some query examples and learn more about each query parameter.\n\r\n\rLearn more about [Pagination in the Master Data API](https://developers.vtex.com/docs/guides/pagination-in-the-master-data-api).\r\n\r\n>ℹ️ Fields flagged as PII (`v-pii`) in the data entity schema are returned with masked values by default. To retrieve the original values, add the `unmasked=true` query parameter.\r\n\r\n>⚠️ Avoid sending too many requests with wildcards (`*`) in the search parameters or that use the `keyword` parameter. This may lead to this endpoint being temporarily blocked for your account. If this happens you will receive an error with status code `503`.\r\n\r\n## Query examples\r\n\r\n| **Query Type** | **Example** |\r\n|-|-|\r\n| **Simple filter** | `/dataentities/Newsletter/search?email=my@email.com` |\r\n| **Complex filter** | `/dataentities/Newsletter/search?_where=(firstName=Jon OR lastName=Smith) OR (createdIn between 2001-01-01 AND 2016-01-01)` |\r\n| **Date range** | `/dataentities/Newsletter/search?_where=createdIn between 2001-01-01 AND 2016-01-01` |\r\n| **Range numeric fields** | `/dataentities/Newsletter/search?_where=age between 18 AND 25` |\r\n| **Partial filter** | `/dataentities/Newsletter/search?firstName=*Maria*` |\r\n| **Filter for null values** | `/dataentities/Newsletter/search?_where=firstName is null` |\r\n| **Filter for non-null values** | `/dataentities/Newsletter/search?_where=firstName is not null` |\r\n| **Filter for difference** | `/dataentities/Newsletter/search?_where=firstName<>maria` |\r\n| **Filter greater than** | `/dataentities/Newsletter/search?_where=number>5` |\r\n| **Filter less than** | `/dataentities/Newsletter/search?_where=date<2001-01-01` |\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "type": "text/plain" }, "url": { @@ -1430,6 +1448,15 @@ }, "key": "_sort", "value": "firstName ASC" + }, + { + "disabled": true, + "description": { + "content": "When set to `true`, fields flagged as PII (`v-pii`) in the data entity schema are returned with their original values. By default (`false`), PII fields are returned with masked values.", + "type": "text/plain" + }, + "key": "unmasked", + "value": "false" } ], "variable": [ @@ -1486,7 +1513,7 @@ "_": { "postman_previewlanguage": "json" }, - "id": "985419b5-a6c0-43de-9a83-dfdcbe826485", + "id": "e26c73b9-f008-4ee9-a99e-4a1c361062dc", "name": "OK", "originalRequest": { "url": { @@ -1535,6 +1562,15 @@ }, "key": "_sort", "value": "firstName ASC" + }, + { + "disabled": true, + "description": { + "content": "When set to `true`, fields flagged as PII (`v-pii`) in the data entity schema are returned with their original values. By default (`false`), PII fields are returned with masked values.", + "type": "text/plain" + }, + "key": "unmasked", + "value": "false" } ], "variable": [] @@ -1607,7 +1643,7 @@ "_": { "postman_previewlanguage": "json" }, - "id": "16519c4e-0615-4184-be33-94acb149da3f", + "id": "3bc3635f-aab8-4807-80d2-36f6c856497c", "name": "Bad Request", "originalRequest": { "url": { @@ -1656,6 +1692,15 @@ }, "key": "_sort", "value": "firstName ASC" + }, + { + "disabled": true, + "description": { + "content": "When set to `true`, fields flagged as PII (`v-pii`) in the data entity schema are returned with their original values. By default (`false`), PII fields are returned with masked values.", + "type": "text/plain" + }, + "key": "unmasked", + "value": "false" } ], "variable": [] @@ -1719,7 +1764,7 @@ "_": { "postman_previewlanguage": "json" }, - "id": "5a504dda-fb85-4d3d-b5f0-f62ac9adc5ed", + "id": "8d5ea014-3a6b-4596-9621-3f7051ab7f45", "name": "Forbidden", "originalRequest": { "url": { @@ -1768,6 +1813,15 @@ }, "key": "_sort", "value": "firstName ASC" + }, + { + "disabled": true, + "description": { + "content": "When set to `true`, fields flagged as PII (`v-pii`) in the data entity schema are returned with their original values. By default (`false`), PII fields are returned with masked values.", + "type": "text/plain" + }, + "key": "unmasked", + "value": "false" } ], "variable": [] @@ -1831,7 +1885,7 @@ "_": { "postman_previewlanguage": "text" }, - "id": "caeba15a-fc82-4d2a-b0da-dbab04f6e4a9", + "id": "4fe1ad6a-0216-48d7-b47a-cd17f5e2fead", "name": "Service Unavailable\n\nWildcard queries temporarily blocked due to excessive usage. Consider adjusting your code to remove them or reduce the rate of search requests with wildcards (*). This temporary block may also be due to excessive use of requests with the parameter `keyword`.", "originalRequest": { "url": { @@ -1880,6 +1934,15 @@ }, "key": "_sort", "value": "firstName ASC" + }, + { + "disabled": true, + "description": { + "content": "When set to `true`, fields flagged as PII (`v-pii`) in the data entity schema are returned with their original values. By default (`false`), PII fields are returned with masked values.", + "type": "text/plain" + }, + "key": "unmasked", + "value": "false" } ], "variable": [] @@ -1934,7 +1997,7 @@ { "listen": "test", "script": { - "id": "26fdbf86-ee87-4e47-a63e-0a26947fab5d", + "id": "2b2d8119-e1f2-49f0-a5c5-a7ff5ca92e0d", "type": "text/javascript", "exec": [ "// Validate status 2xx \npm.test(\"[GET]::/api/dataentities/:dataEntityName/search - Status code is 2xx\", function () {\n pm.response.to.be.success;\n});\n", @@ -1953,7 +2016,7 @@ "event": [] }, { - "id": "475e6515-cc62-4fa4-ba6e-f04c1219693a", + "id": "0449309f-b331-4eac-9294-527bc9da2308", "name": "Scroll", "description": { "content": "", @@ -1961,12 +2024,12 @@ }, "item": [ { - "id": "fc192fdd-0f29-411b-8759-6dc435d80103", + "id": "6921a18e-de4f-4616-9f7c-df09848fbaa6", "name": "Scroll documents", "request": { "name": "Scroll documents", "description": { - "content": "Returns a list of documents according to query parameter filters. If you need to query the entire database, or your collection is over 10000 documents, use this endpoint.\r\n\r\nIn the first request, the `X-VTEX-MD-TOKEN` token will be obtained in the response header. This token must be passed to the next request in the `_token` query string parameter. The token expires after 20 minutes of inactivity, and each request made with the token during this time resets the expiration timer.\r\n\r\nAfter the token is obtained, it is no longer necessary to send the filter or document size per page parameters. You only need to resend the token until the document collection is empty.\r\n\r\nFirst request:\r\n```\r\n/dataentities/Newsletter/scroll?isCluster=true&_size=250&_fields=email,firstName\r\n```\r\n\r\nRetrieve the token in the header `X-VTEX-MD-TOKEN` from the first request's response and use it to make the following requests.\r\n\r\nSubsequent requests:\r\n```\r\n/dataentities/Newsletter/scroll?_token={tokenValue}\r\n```\n\r\n\rLearn more about [Pagination in the Master Data API](https://developers.vtex.com/docs/guides/pagination-in-the-master-data-api).\r\n\r\n>⚠️ Avoid sending too many requests with wildcards (`*`) in the search parameters or using the `keyword` parameter. This may lead to this endpoint being temporarily blocked for your account. If this happens you will receive an error with status code `429`.\r\n\r\n## Query examples\r\n\r\n| **Query Type** | **Example** |\r\n|-|-|\r\n| **Simple filter** | `/dataentities/Newsletter/scroll?email=my@email.com` |\r\n| **Complex filter** | `/dataentities/Newsletter/scroll?_where=(firstName=Jon OR lastName=Smith) OR (createdIn between 2001-01-01 AND 2016-01-01)` |\r\n| **Date range** | `/dataentities/Newsletter/scroll?_where=createdIn between 2001-01-01 AND 2016-01-01` |\r\n| **Range numeric fields** | `/dataentities/Newsletter/scroll?_where=age between 18 AND 25` |\r\n| **Partial filter** | `/dataentities/Newsletter/scroll?firstName=*Maria*` |\r\n| **Filter for null values** | `/dataentities/Newsletter/scroll?_where=firstName is null` |\r\n| **Filter for non-null values** | `/dataentities/Newsletter/scroll?_where=firstName is not null` |\r\n| **Filter for difference** | `/dataentities/Newsletter/scroll?_where=firstName<>maria` |\r\n| **Filter greater than** | `/dataentities/Newsletter/scroll?_where=number>5` |\r\n| **Filter less than** | `/dataentities/Newsletter/scroll?_where=date<2001-01-01` |\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", + "content": "Returns a list of documents according to query parameter filters. If you need to query the entire database, or your collection is over 10000 documents, use this endpoint.\r\n\r\nIn the first request, the `X-VTEX-MD-TOKEN` token will be obtained in the response header. This token must be passed to the next request in the `_token` query string parameter. The token expires after 20 minutes of inactivity, and each request made with the token during this time resets the expiration timer.\r\n\r\nAfter the token is obtained, it is no longer necessary to send the filter or document size per page parameters. You only need to resend the token until the document collection is empty.\r\n\r\nFirst request:\r\n```\r\n/dataentities/Newsletter/scroll?isCluster=true&_size=250&_fields=email,firstName\r\n```\r\n\r\nRetrieve the token in the header `X-VTEX-MD-TOKEN` from the first request's response and use it to make the following requests.\r\n\r\nSubsequent requests:\r\n```\r\n/dataentities/Newsletter/scroll?_token={tokenValue}\r\n```\n\r\n\rLearn more about [Pagination in the Master Data API](https://developers.vtex.com/docs/guides/pagination-in-the-master-data-api).\r\n\r\n>ℹ️ Fields flagged as PII (`v-pii`) in the data entity schema are returned with masked values by default. To retrieve the original values, add the `unmasked=true` query parameter.\r\n\r\n>⚠️ Avoid sending too many requests with wildcards (`*`) in the search parameters or using the `keyword` parameter. This may lead to this endpoint being temporarily blocked for your account. If this happens you will receive an error with status code `429`.\r\n\r\n## Query examples\r\n\r\n| **Query Type** | **Example** |\r\n|-|-|\r\n| **Simple filter** | `/dataentities/Newsletter/scroll?email=my@email.com` |\r\n| **Complex filter** | `/dataentities/Newsletter/scroll?_where=(firstName=Jon OR lastName=Smith) OR (createdIn between 2001-01-01 AND 2016-01-01)` |\r\n| **Date range** | `/dataentities/Newsletter/scroll?_where=createdIn between 2001-01-01 AND 2016-01-01` |\r\n| **Range numeric fields** | `/dataentities/Newsletter/scroll?_where=age between 18 AND 25` |\r\n| **Partial filter** | `/dataentities/Newsletter/scroll?firstName=*Maria*` |\r\n| **Filter for null values** | `/dataentities/Newsletter/scroll?_where=firstName is null` |\r\n| **Filter for non-null values** | `/dataentities/Newsletter/scroll?_where=firstName is not null` |\r\n| **Filter for difference** | `/dataentities/Newsletter/scroll?_where=firstName<>maria` |\r\n| **Filter greater than** | `/dataentities/Newsletter/scroll?_where=number>5` |\r\n| **Filter less than** | `/dataentities/Newsletter/scroll?_where=date<2001-01-01` |\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "type": "text/plain" }, "url": { @@ -2033,6 +2096,15 @@ }, "key": "_sort", "value": "firstName ASC" + }, + { + "disabled": true, + "description": { + "content": "When set to `true`, fields flagged as PII (`v-pii`) in the data entity schema are returned with their original values. By default (`false`), PII fields are returned with masked values.", + "type": "text/plain" + }, + "key": "unmasked", + "value": "false" } ], "variable": [ @@ -2080,7 +2152,7 @@ "_": { "postman_previewlanguage": "json" }, - "id": "8da002c0-a9d0-4c37-a476-801275950471", + "id": "c688aa8f-8791-447e-95c4-298c058c3eba", "name": "OK", "originalRequest": { "url": { @@ -2147,6 +2219,15 @@ }, "key": "_sort", "value": "firstName ASC" + }, + { + "disabled": true, + "description": { + "content": "When set to `true`, fields flagged as PII (`v-pii`) in the data entity schema are returned with their original values. By default (`false`), PII fields are returned with masked values.", + "type": "text/plain" + }, + "key": "unmasked", + "value": "false" } ], "variable": [] @@ -2200,7 +2281,7 @@ "type": "text/plain" }, "key": "X-VTEX-MD-TOKEN", - "value": "cillum incididunt voluptate" + "value": "commodo" }, { "disabled": true, @@ -2209,7 +2290,7 @@ "type": "text/plain" }, "key": "REST-Content-Total", - "value": "culpa amet Lorem" + "value": "ut veniam exercitation" } ], "body": "[\n {\n \"id\": \"b818cbda-e489-11e6-94f4-0ac138d2d42e\",\n \"accountId\": \"14af940d-9300-4279-9355-61d44c2ff879\",\n \"accountName\": \"apiexamples\",\n \"dataEntityId\": \"Newsletter\"\n }\n]", @@ -2219,7 +2300,7 @@ "_": { "postman_previewlanguage": "json" }, - "id": "22a7324e-606b-456a-8096-2ba3ba6995a7", + "id": "7b8d2238-fd0f-4701-9a46-b56564973d07", "name": "Bad Request", "originalRequest": { "url": { @@ -2286,6 +2367,15 @@ }, "key": "_sort", "value": "firstName ASC" + }, + { + "disabled": true, + "description": { + "content": "When set to `true`, fields flagged as PII (`v-pii`) in the data entity schema are returned with their original values. By default (`false`), PII fields are returned with masked values.", + "type": "text/plain" + }, + "key": "unmasked", + "value": "false" } ], "variable": [] @@ -2340,7 +2430,7 @@ "_": { "postman_previewlanguage": "text" }, - "id": "d5a93c31-0d4a-4073-a022-a9d720c69e25", + "id": "e97774be-2d85-47eb-b44e-2fd5459a655f", "name": "Too Many Requests\n\nWildcard queries temporarily blocked due to excessive usage. Consider adjusting your code to remove them or reduce the rate of search requests with wildcards (*). This temporary block may also be due to excessive use of requests with the parameter `keyword`.", "originalRequest": { "url": { @@ -2407,6 +2497,15 @@ }, "key": "_sort", "value": "firstName ASC" + }, + { + "disabled": true, + "description": { + "content": "When set to `true`, fields flagged as PII (`v-pii`) in the data entity schema are returned with their original values. By default (`false`), PII fields are returned with masked values.", + "type": "text/plain" + }, + "key": "unmasked", + "value": "false" } ], "variable": [] @@ -2452,7 +2551,7 @@ { "listen": "test", "script": { - "id": "6222cb76-06de-4a0f-8dfe-a6abd60d20e2", + "id": "a9cb6535-ced9-416b-8683-a8bbbb19e1a3", "type": "text/javascript", "exec": [ "// Validate status 2xx \npm.test(\"[GET]::/api/dataentities/:dataEntityName/scroll - Status code is 2xx\", function () {\n pm.response.to.be.success;\n});\n", @@ -2471,7 +2570,7 @@ "event": [] }, { - "id": "a2e8fe16-2f03-4d34-88b1-c83789f1fcc9", + "id": "a7611304-136e-45ba-b319-9a3b06f1d9c2", "name": "Schemas", "description": { "content": "", @@ -2479,7 +2578,7 @@ }, "item": [ { - "id": "9ded0f3f-c125-4c01-af11-78882d6bd59d", + "id": "ef87cdf1-9eb1-4bc1-a6cb-63b9a60ea1f9", "name": "Get schemas", "request": { "name": "Get schemas", @@ -2534,7 +2633,7 @@ "_": { "postman_previewlanguage": "json" }, - "id": "833a7ddc-063c-44e0-b988-10a977253bda", + "id": "1bea1099-2237-4ffe-a7c7-944ea1f7736e", "name": "OK", "originalRequest": { "url": { @@ -2592,13 +2691,13 @@ { "listen": "test", "script": { - "id": "d7b6ca48-fb1d-4a78-9bd4-d45d2e6ff559", + "id": "baff189e-66df-4911-957e-0c43c1834202", "type": "text/javascript", "exec": [ "// Validate status 2xx \npm.test(\"[GET]::/api/dataentities/:dataEntityName/schemas - Status code is 2xx\", function () {\n pm.response.to.be.success;\n});\n", "// Validate if response header has matching content-type\npm.test(\"[GET]::/api/dataentities/:dataEntityName/schemas - Content-Type is application/json\", function () {\n pm.expect(pm.response.headers.get(\"Content-Type\")).to.include(\"application/json\");\n});\n", "// Validate if response has JSON Body \npm.test(\"[GET]::/api/dataentities/:dataEntityName/schemas - Response has JSON Body\", function () {\n pm.response.to.have.jsonBody();\n});\n", - "// Response Validation\nconst schema = {\"type\":\"array\",\"description\":\"Array with existing schemas. In case there is only one existing schema, it will be an object instead, without the `name` property and the named `schema` object, following the same structure as the [Get schema by name](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/schemas/-schemaName-?endpoint=get-/api/dataentities/-dataEntityName-/schemas/-schemaName-) endpoint response.\",\"items\":{\"title\":\"GetSchemasResponse\",\"required\":[\"name\",\"schema\"],\"type\":\"object\",\"description\":\"Schema.\",\"properties\":{\"name\":{\"type\":\"string\",\"description\":\"Schema name.\"},\"schema\":{\"type\":\"object\",\"description\":\"Object with schema properties.\",\"properties\":{\"properties\":{\"type\":\"object\",\"description\":\"Object containing schema properties.\",\"properties\":{\"name\":{\"type\":\"object\",\"description\":\"Property name.\",\"required\":[\"type\"],\"properties\":{\"type\":{\"type\":\"string\",\"description\":\"Type of property.\",\"enum\":[\"array\",\"boolean\",\"integer\",\"number\",\"object\",\"string\"]}}}}}}}}}}\n\n// Validate if response matches JSON schema \npm.test(\"[GET]::/api/dataentities/:dataEntityName/schemas - Schema is valid\", function() {\n pm.response.to.have.jsonSchema(schema,{unknownFormats: [\"int32\", \"int64\", \"float\", \"double\"]});\n});\n" + "// Response Validation\nconst schema = {\"type\":\"array\",\"description\":\"Array with existing schemas. In case there is only one existing schema, it will be an object instead, without the `name` property and the named `schema` object, following the same structure as the [Get schema by name](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/schemas/-schemaName-?endpoint=get-/api/dataentities/-dataEntityName-/schemas/-schemaName-) endpoint response.\",\"items\":{\"title\":\"GetSchemasResponse\",\"required\":[\"name\",\"schema\"],\"type\":\"object\",\"description\":\"Schema.\",\"properties\":{\"name\":{\"type\":\"string\",\"description\":\"Schema name.\"},\"schema\":{\"type\":\"object\",\"description\":\"Object with schema properties.\",\"properties\":{\"properties\":{\"type\":\"object\",\"description\":\"Object containing schema properties.\",\"properties\":{\"name\":{\"type\":\"object\",\"description\":\"Property name.\",\"required\":[\"type\"],\"properties\":{\"type\":{\"type\":\"string\",\"description\":\"Type of property.\",\"enum\":[\"array\",\"boolean\",\"integer\",\"number\",\"object\",\"string\"]}}}}},\"v-pii\":{\"type\":\"array\",\"items\":{\"type\":\"string\"},\"description\":\"Names of properties flagged as personally identifiable information (PII).\"}}}}}}\n\n// Validate if response matches JSON schema \npm.test(\"[GET]::/api/dataentities/:dataEntityName/schemas - Schema is valid\", function() {\n pm.response.to.have.jsonSchema(schema,{unknownFormats: [\"int32\", \"int64\", \"float\", \"double\"]});\n});\n" ] } } @@ -2608,7 +2707,7 @@ } }, { - "id": "88490255-ead4-4752-9d00-8b6514402685", + "id": "b83b0ac0-4b0b-48ff-8ce7-3818e6fdb724", "name": "Get schema by name", "request": { "name": "Get schema by name", @@ -2674,7 +2773,7 @@ "_": { "postman_previewlanguage": "json" }, - "id": "30ba703d-faf5-4337-9114-6cabef7eba6e", + "id": "ac5e3394-bcd2-471d-b1e4-54f975fbdfe4", "name": "OK", "originalRequest": { "url": { @@ -2733,13 +2832,13 @@ { "listen": "test", "script": { - "id": "ba5e29a5-e119-44d8-8fbb-0682cc41999e", + "id": "92fb6005-0a5d-4bae-b771-53edca879b83", "type": "text/javascript", "exec": [ "// Validate status 2xx \npm.test(\"[GET]::/api/dataentities/:dataEntityName/schemas/:schemaName - Status code is 2xx\", function () {\n pm.response.to.be.success;\n});\n", "// Validate if response header has matching content-type\npm.test(\"[GET]::/api/dataentities/:dataEntityName/schemas/:schemaName - Content-Type is application/json\", function () {\n pm.expect(pm.response.headers.get(\"Content-Type\")).to.include(\"application/json\");\n});\n", "// Validate if response has JSON Body \npm.test(\"[GET]::/api/dataentities/:dataEntityName/schemas/:schemaName - Response has JSON Body\", function () {\n pm.response.to.have.jsonBody();\n});\n", - "// Response Validation\nconst schema = {\"title\":\"SaveschemabynameRequest\",\"required\":[\"properties\"],\"type\":\"object\",\"description\":\"JSON Schema of the data entity. Add `v-indexed` with an array of property names to make those fields filterable and sortable in /search and /scroll.\",\"properties\":{\"properties\":{\"type\":\"object\",\"description\":\"Object containing schema properties.\",\"properties\":{\"name\":{\"type\":\"object\",\"description\":\"Property name.\",\"required\":[\"type\"],\"properties\":{\"type\":{\"type\":\"string\",\"description\":\"Type of property.\",\"enum\":[\"array\",\"boolean\",\"integer\",\"number\",\"object\",\"string\"]}}}}},\"v-indexed\":{\"type\":\"array\",\"items\":{\"type\":\"string\"},\"description\":\"Names of properties to index for /search, /scroll, and _sort. Required for reliable filtering (e.g. _where=field=value) and sorting (_sort=field ASC). Indexing is asynchronous after schema save.\"}}}\n\n// Validate if response matches JSON schema \npm.test(\"[GET]::/api/dataentities/:dataEntityName/schemas/:schemaName - Schema is valid\", function() {\n pm.response.to.have.jsonSchema(schema,{unknownFormats: [\"int32\", \"int64\", \"float\", \"double\"]});\n});\n" + "// Response Validation\nconst schema = {\"title\":\"SaveschemabynameRequest\",\"required\":[\"properties\"],\"type\":\"object\",\"description\":\"JSON Schema of the data entity. Add `v-indexed` with an array of property names to make those fields filterable and sortable in /search and /scroll. Add `v-pii` with an array of property names to flag fields as PII, which will be masked by default on retrieval.\",\"properties\":{\"properties\":{\"type\":\"object\",\"description\":\"Object containing schema properties.\",\"properties\":{\"name\":{\"type\":\"object\",\"description\":\"Property name.\",\"required\":[\"type\"],\"properties\":{\"type\":{\"type\":\"string\",\"description\":\"Type of property.\",\"enum\":[\"array\",\"boolean\",\"integer\",\"number\",\"object\",\"string\"]}}}}},\"v-indexed\":{\"type\":\"array\",\"items\":{\"type\":\"string\"},\"description\":\"Names of properties to index for /search, /scroll, and _sort. Required for reliable filtering (e.g. _where=field=value) and sorting (_sort=field ASC). Indexing is asynchronous after schema save.\"},\"v-pii\":{\"type\":\"array\",\"items\":{\"type\":\"string\"},\"description\":\"Names of properties that contain personally identifiable information (PII). Fields listed here are handled according to data protection best practices and returned with masked values by default. To retrieve original values, use the `unmasked=true` query parameter on document retrieval endpoints.\"}}}\n\n// Validate if response matches JSON schema \npm.test(\"[GET]::/api/dataentities/:dataEntityName/schemas/:schemaName - Schema is valid\", function() {\n pm.response.to.have.jsonSchema(schema,{unknownFormats: [\"int32\", \"int64\", \"float\", \"double\"]});\n});\n" ] } } @@ -2749,12 +2848,12 @@ } }, { - "id": "d535557f-8249-491f-b55f-ebf6d2e84b6d", + "id": "e76b8c8b-a096-4e17-8a59-7a960c8d6cd6", "name": "Save schema by name", "request": { "name": "Save schema by name", "description": { - "content": "Creates or edits a data entity schema. Learn more about [Master Data schemas](https://developers.vtex.com/vtex-rest-api/docs/master-data-schema-lifecycle).\r\n\r\n> Note that if you send a `schemaName` that does not exist for that data entity, this request will create it.\r\n\r\nThis request can also be used to [create or edit Master Data v2 triggers](https://developers.vtex.com/vtex-rest-api/docs/setting-up-triggers-in-master-data-v2).\r\n\r\n> Each Master Data v2 data entity can have up to 60 schemas.\r\n\r\n## Indexing fields for search, scroll and sort\r\n\r\nTo filter or sort by a field in [Search documents](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/search) or [Scroll documents](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/scroll), add that field to the `v-indexed` array in the schema. This is the schema-level index (separate from the [indices](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/indices) endpoint).\r\n\r\n- `v-indexed`: Array of property names that Master Data v2 must index for `/search`, `/scroll`, and `_sort`. Use it whenever you want to use `_where`, `_sort`, or range filters (e.g. `_where=postalCode between 10000 AND 20000`) on that field. Indexing runs asynchronously after the schema is saved.\r\n- `filterable` and `searchable`: Apply to the UI (e.g. Master Data v1/CRM-style behavior). They do **not** create the index used by `/search`; only `v-indexed` does.\r\n\r\n**Example request body with `v-indexed`:**\r\n\r\n```json\r\n{\r\n \"properties\": {\r\n \"skuId\": { \"type\": \"string\" },\r\n \"postalCode\": { \"type\": \"string\" }\r\n },\r\n \"v-indexed\": [\"postalCode\"]\r\n}\r\n```\r\n\r\n> ℹ️ Use `v-indexed` when you need fields to be filterable/sortable in `/search`. Use the [/indices](https://developers.vtex.com/docs/api-reference/master-data-api-v2#put-/api/dataentities/-dataEntityName-/indices) endpoint when you need entity-level uniqueness, composite keys, or relationships between entities.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", + "content": "Creates or edits a data entity schema. Learn more about [Master Data schemas](https://developers.vtex.com/vtex-rest-api/docs/master-data-schema-lifecycle).\r\n\r\n> Note that if you send a `schemaName` that does not exist for that data entity, this request will create it.\r\n\r\nThis request can also be used to [create or edit Master Data v2 triggers](https://developers.vtex.com/vtex-rest-api/docs/setting-up-triggers-in-master-data-v2).\r\n\r\n> Each Master Data v2 data entity can have up to 60 schemas.\r\n\r\n## Indexing fields for search, scroll and sort\r\n\r\nTo filter or sort by a field in [Search documents](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/search) or [Scroll documents](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/scroll), add that field to the `v-indexed` array in the schema. This is the schema-level index (separate from the [indices](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/indices) endpoint).\r\n\r\n- `v-indexed`: Array of property names that Master Data v2 must index for `/search`, `/scroll`, and `_sort`. Use it whenever you want to use `_where`, `_sort`, or range filters (e.g. `_where=postalCode between 10000 AND 20000`) on that field. Indexing runs asynchronously after the schema is saved.\r\n- `filterable` and `searchable`: Apply to the UI (e.g. Master Data v1/CRM-style behavior). They do **not** create the index used by `/search`; only `v-indexed` does.\r\n\r\n**Example request body with `v-indexed`:**\r\n\r\n```json\r\n{\r\n \"properties\": {\r\n \"skuId\": { \"type\": \"string\" },\r\n \"postalCode\": { \"type\": \"string\" }\r\n },\r\n \"v-indexed\": [\"postalCode\"]\r\n}\r\n```\r\n\r\n> ℹ️ Use `v-indexed` when you need fields to be filterable/sortable in `/search`. Use the [/indices](https://developers.vtex.com/docs/api-reference/master-data-api-v2#put-/api/dataentities/-dataEntityName-/indices) endpoint when you need entity-level uniqueness, composite keys, or relationships between entities.\r\n\r\n## Flagging fields as PII\r\n\r\nTo flag fields that contain personally identifiable information (PII), add those field names to the `v-pii` array in the schema. Fields listed in `v-pii` are handled according to data protection best practices: their values are stored securely and returned masked by default when retrieving documents.\r\n\r\nTo retrieve the original (unmasked) values of PII fields, pass the query parameter `unmasked=true` in [Get document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/documents/-id-), [Search documents](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/search), or [Scroll documents](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/scroll).\r\n\r\n**Example request body with `v-pii`:**\r\n\r\n```json\r\n{\r\n \"properties\": {\r\n \"email\": { \"type\": \"string\" },\r\n \"firstName\": { \"type\": \"string\" },\r\n \"document\": { \"type\": \"string\" }\r\n },\r\n \"v-pii\": [\"email\", \"document\"]\r\n}\r\n```\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "type": "text/plain" }, "url": { @@ -2819,7 +2918,7 @@ "_": { "postman_previewlanguage": "json" }, - "id": "65156947-ffef-43b4-a2b6-b8a1cf90bce8", + "id": "8823ddb9-3a81-4e93-9f86-b7aaf4c62de2", "name": "Minimal schema", "originalRequest": { "url": { @@ -2881,7 +2980,7 @@ "_": { "postman_previewlanguage": "json" }, - "id": "2317b531-4ffa-4a06-936f-e542f03c82c8", + "id": "b76522f9-f00a-4020-bbe2-74d4af1da0ca", "name": "Schema with v-indexed for filter and sort", "originalRequest": { "url": { @@ -2938,13 +3037,75 @@ ], "body": "{\n \"Message\": \"JSON Schema persisted successfully. Revalidation and indexing process running in background.\"\n}", "cookie": [] + }, + { + "_": { + "postman_previewlanguage": "json" + }, + "id": "5b77302a-94f5-4575-83ab-13471e18229f", + "name": "Schema with v-pii for PII masking", + "originalRequest": { + "url": { + "path": [ + "api", + "dataentities", + ":dataEntityName", + "schemas", + ":schemaName" + ], + "host": [ + "{{baseUrl}}" + ], + "query": [], + "variable": [] + }, + "header": [ + { + "key": "Content-Type", + "value": "application/json" + }, + { + "key": "Accept", + "value": "application/json" + }, + { + "description": { + "content": "Added as a part of security scheme: apikey", + "type": "text/plain" + }, + "key": "X-VTEX-API-AppKey", + "value": "" + } + ], + "method": "PUT", + "body": { + "mode": "raw", + "raw": "{\n \"properties\": {\n \"email\": {\n \"type\": \"string\"\n },\n \"firstName\": {\n \"type\": \"string\"\n },\n \"document\": {\n \"type\": \"string\"\n }\n },\n \"v-pii\": [\n \"email\",\n \"document\"\n ]\n}", + "options": { + "raw": { + "headerFamily": "json", + "language": "json" + } + } + } + }, + "status": "OK", + "code": 200, + "header": [ + { + "key": "Content-Type", + "value": "application/json" + } + ], + "body": "{\n \"Message\": \"JSON Schema persisted successfully. Revalidation and indexing process running in background.\"\n}", + "cookie": [] } ], "event": [ { "listen": "test", "script": { - "id": "8bc98c5d-e250-4dc1-8d12-bee8acafda3f", + "id": "0662ec44-299c-4f47-abb9-e66b621ba92f", "type": "text/javascript", "exec": [ "// Validate status 2xx \npm.test(\"[PUT]::/api/dataentities/:dataEntityName/schemas/:schemaName - Status code is 2xx\", function () {\n pm.response.to.be.success;\n});\n", @@ -2960,7 +3121,7 @@ } }, { - "id": "9201809d-a467-4b1f-afdb-a61eb10be1ca", + "id": "e58f54b8-c87f-4b48-87d5-c4cb549e7262", "name": "Delete schema by name", "request": { "name": "Delete schema by name", @@ -3022,7 +3183,7 @@ "_": { "postman_previewlanguage": "text" }, - "id": "d15eb5ed-1667-4f03-9e3d-d0fbb4b05199", + "id": "e4d3e7d8-151b-4456-8b5a-45fb3d7ea717", "name": "No Content", "originalRequest": { "url": { @@ -3071,7 +3232,7 @@ { "listen": "test", "script": { - "id": "24498e5e-9e79-479f-bcfe-c6b68085bfab", + "id": "7cc6d982-a6d8-417a-a0fa-f202ae03c23e", "type": "text/javascript", "exec": [ "// Validate status 2xx \npm.test(\"[DELETE]::/api/dataentities/:dataEntityName/schemas/:schemaName - Status code is 2xx\", function () {\n pm.response.to.be.success;\n});\n", @@ -3088,7 +3249,7 @@ "event": [] }, { - "id": "be2b491f-69a8-4ea8-8fc6-a7035a173f2b", + "id": "610bd0b0-80cc-4931-b386-35fc55798e1d", "name": "Indices", "description": { "content": "", @@ -3096,7 +3257,7 @@ }, "item": [ { - "id": "43b0a464-8b12-43d5-9abb-19558a8aa2dd", + "id": "793d887a-5741-4287-bcca-4065d8adcc53", "name": "Get indices", "request": { "name": "Get indices", @@ -3151,7 +3312,7 @@ "_": { "postman_previewlanguage": "json" }, - "id": "20619773-b270-4c78-aed1-1ba9a1b42921", + "id": "a067b9a3-9fc5-4790-8542-c7c30b11216f", "name": "OK", "originalRequest": { "url": { @@ -3209,7 +3370,7 @@ { "listen": "test", "script": { - "id": "3e9583cc-33a1-40ca-b331-ee6a85d56a43", + "id": "462c6258-fcd9-4bcb-9773-3c4ba078ae72", "type": "text/javascript", "exec": [ "// Validate status 2xx \npm.test(\"[GET]::/api/dataentities/:dataEntityName/indices - Status code is 2xx\", function () {\n pm.response.to.be.success;\n});\n", @@ -3225,7 +3386,7 @@ } }, { - "id": "2ea4cee4-9272-4d8b-b9c3-38992dcb75c6", + "id": "dbe54166-c12b-48cb-9eb0-c73e6dbf8051", "name": "Create index", "request": { "name": "Create index", @@ -3280,7 +3441,7 @@ "_": { "postman_previewlanguage": "text" }, - "id": "7d1746b9-198d-492e-a226-8ff477706674", + "id": "30ba9dad-f709-4b94-a4fa-e2938bf37a5c", "name": "OK", "originalRequest": { "url": { @@ -3332,7 +3493,7 @@ { "listen": "test", "script": { - "id": "2130f153-9433-441a-9bd4-49c6cce7fd1e", + "id": "91f73ef4-abdb-4d34-9c68-3d9f8591c542", "type": "text/javascript", "exec": [ "// Validate status 2xx \npm.test(\"[PUT]::/api/dataentities/:dataEntityName/indices - Status code is 2xx\", function () {\n pm.response.to.be.success;\n});\n" @@ -3345,7 +3506,7 @@ } }, { - "id": "da2ed317-7765-4594-853c-e4dc21b9810d", + "id": "9b3139ef-a8c0-44cc-9836-b4cc527b2541", "name": "Get index by name", "request": { "name": "Get index by name", @@ -3411,7 +3572,7 @@ "_": { "postman_previewlanguage": "json" }, - "id": "55f295e9-c990-474f-9403-a1d9a1819424", + "id": "e46dd6bb-7f1e-403c-8558-688790e1a2f4", "name": "OK", "originalRequest": { "url": { @@ -3470,7 +3631,7 @@ { "listen": "test", "script": { - "id": "abe1c960-1464-4828-b40a-a417b802b9da", + "id": "95eeaa52-fea3-4060-a0f7-72d192f69589", "type": "text/javascript", "exec": [ "// Validate status 2xx \npm.test(\"[GET]::/api/dataentities/:dataEntityName/indices/:index_name - Status code is 2xx\", function () {\n pm.response.to.be.success;\n});\n", @@ -3486,7 +3647,7 @@ } }, { - "id": "74221047-8be0-411b-a5ea-53b1bb536e36", + "id": "35a2d504-34c3-45f2-9df3-1200a377492d", "name": "Delete index by name", "request": { "name": "Delete index by name", @@ -3548,7 +3709,7 @@ "_": { "postman_previewlanguage": "text" }, - "id": "47d7c628-6ff8-42bf-b163-c2fb5afb88f0", + "id": "220b2294-1e28-49e7-bd98-5b7a08e610f8", "name": "No Content", "originalRequest": { "url": { @@ -3597,7 +3758,7 @@ { "listen": "test", "script": { - "id": "b10a8b34-0e56-4086-981f-6aaa743f7e7f", + "id": "50860b21-a2ce-4912-b5aa-ad737e7a3ef5", "type": "text/javascript", "exec": [ "// Validate status 2xx \npm.test(\"[DELETE]::/api/dataentities/:dataEntityName/indices/:index_name - Status code is 2xx\", function () {\n pm.response.to.be.success;\n});\n", @@ -3614,7 +3775,7 @@ "event": [] }, { - "id": "753be904-1b16-46e0-a9b5-0dfc2d7ac1c3", + "id": "8a07fa36-8a40-46a7-9065-5eeceb82fdc5", "name": "Clusters", "description": { "content": "", @@ -3622,7 +3783,7 @@ }, "item": [ { - "id": "eca3650b-2dfe-479f-8565-dfc9b3f5079b", + "id": "e2e974f8-fb34-4938-a11a-046910788b95", "name": "Validate document by clusters", "request": { "name": "Validate document by clusters", @@ -3702,7 +3863,7 @@ "_": { "postman_previewlanguage": "json" }, - "id": "7dd7d145-bcc3-472f-9074-a0bc5c583940", + "id": "83d14af4-564a-4b22-8aec-8d059fdc8c7a", "name": "OK", "originalRequest": { "url": { @@ -3775,7 +3936,7 @@ { "listen": "test", "script": { - "id": "3120874e-f852-4c7a-ad86-604a2deb0fd4", + "id": "db200c45-9cfa-4c4c-8b25-e6c90ceeee76", "type": "text/javascript", "exec": [ "// Validate status 2xx \npm.test(\"[POST]::/api/dataentities/:dataEntityName/documents/:id/clusters - Status code is 2xx\", function () {\n pm.response.to.be.success;\n});\n", @@ -3794,7 +3955,7 @@ "event": [] }, { - "id": "8d436920-4f47-4b22-bfe3-5fdb5850d722", + "id": "695ba770-d9e3-4e0a-ad8b-c9195df641e2", "name": "Versions", "description": { "content": "", @@ -3802,7 +3963,7 @@ }, "item": [ { - "id": "5f7cddaf-34bd-41dc-bb63-64cbd2eb3c65", + "id": "c24335b9-7779-49dc-b3cc-39f2c74fea81", "name": "List versions", "request": { "name": "List versions", @@ -3897,7 +4058,7 @@ "_": { "postman_previewlanguage": "json" }, - "id": "90e9c0ac-510d-4ca2-87fc-25a2c77112a8", + "id": "4139e3d0-e5fe-44f8-a947-b22b248b5b68", "name": "OK", "originalRequest": { "url": { @@ -3985,7 +4146,7 @@ { "listen": "test", "script": { - "id": "7bc2eef5-e2f2-473f-9da3-515f417ee422", + "id": "7b243e60-a3e1-4105-8328-e551038236a5", "type": "text/javascript", "exec": [ "// Validate status 2xx \npm.test(\"[GET]::/api/dataentities/:dataEntityName/documents/:id/versions - Status code is 2xx\", function () {\n pm.response.to.be.success;\n});\n", @@ -4001,7 +4162,7 @@ } }, { - "id": "4da59637-6bdd-4e12-86df-4968653f3e58", + "id": "03c41cc5-9e77-42af-84f3-bf60856b01b6", "name": "Get version", "request": { "name": "Get version", @@ -4088,7 +4249,7 @@ "_": { "postman_previewlanguage": "json" }, - "id": "331721a2-dd20-4534-8255-c3fbc3f53b2d", + "id": "6fc324d6-b54b-439a-b323-55d3c672d14d", "name": "OK", "originalRequest": { "url": { @@ -4158,7 +4319,7 @@ { "listen": "test", "script": { - "id": "46de3a72-2433-410c-8e3d-69afe9506bd2", + "id": "78954b98-c6a4-4b2b-a8c7-c2076178be9b", "type": "text/javascript", "exec": [ "// Validate status 2xx \npm.test(\"[GET]::/api/dataentities/:dataEntityName/documents/:id/versions/:versionId - Status code is 2xx\", function () {\n pm.response.to.be.success;\n});\n", @@ -4174,7 +4335,7 @@ } }, { - "id": "0ea478cf-6485-4ae4-a668-165ba851d8bb", + "id": "30ca4e88-3e98-4d76-b4b2-3b0c8bdd0411", "name": "Update version", "request": { "name": "Update version", @@ -4261,7 +4422,7 @@ "_": { "postman_previewlanguage": "json" }, - "id": "1e8771d1-64be-461f-a526-f0df8d61131f", + "id": "0eee6d06-2224-4e00-ba64-7fc7a82c7ea1", "name": "OK", "originalRequest": { "url": { @@ -4330,7 +4491,7 @@ "_": { "postman_previewlanguage": "text" }, - "id": "d9df1531-6275-4a23-9379-c7ddd4d90f2d", + "id": "2c07dfc1-f678-4055-add9-09084af06640", "name": "Not Modified", "originalRequest": { "url": { @@ -4390,7 +4551,7 @@ { "listen": "test", "script": { - "id": "b4bf751d-4e6f-4b2c-8cf0-caa2c2a0d87d", + "id": "f0c4c24d-4012-42fa-a272-ef3290a7babb", "type": "text/javascript", "exec": [ "// Validate status 2xx \npm.test(\"[PUT]::/api/dataentities/:dataEntityName/documents/:id/versions/:versionId - Status code is 2xx\", function () {\n pm.response.to.be.success;\n});\n", @@ -4448,7 +4609,7 @@ } ], "info": { - "_postman_id": "688a451e-ed75-4f71-b0ac-efa28cfdee37", + "_postman_id": "c5e2ef5c-1f65-490e-b9a4-4f1c0d67ecdf", "name": "Master Data API - v2", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", "description": { From 2efd920c7c1fe43e4542750d1720791c96a9a5c8 Mon Sep 17 00:00:00 2001 From: Pedro Antunes <47991446+PedroAntunesCosta@users.noreply.github.com> Date: Thu, 23 Apr 2026 12:19:24 -0300 Subject: [PATCH 3/8] docs: add personal data fields support to Master Data API v2 Add new POST /personalData endpoint for configuring which entity fields contain personal data, with data subject ownership support. Add openData query param to read endpoints for unmasking, and dataSubject query param to write endpoints for GDPR compliance. Remove previous v-pii schema approach per the updated technical proposal. --- VTEX - Master Data API - v2.json | 156 +++++++++++++++++++++---------- 1 file changed, 109 insertions(+), 47 deletions(-) diff --git a/VTEX - Master Data API - v2.json b/VTEX - Master Data API - v2.json index fe3f81c4c..278e773c7 100644 --- a/VTEX - Master Data API - v2.json +++ b/VTEX - Master Data API - v2.json @@ -2,7 +2,7 @@ "openapi": "3.0.0", "info": { "title": "Master Data API - v2", - "description": ">ℹ️ Master Data v2 is not compatible with data entities from previous versions, such as CL and AD.\r\n\r\n[Master Data](https://developers.vtex.com/docs/guides/master-data-introduction) is a secure, fast, scalable, and extensible solution that allows users to create their own entities, store data, and retrieve information directly from the storefront or external integrations.\r\n\r\nSeveral internal VTEX modules use Master Data as a data repository, including Orders and Sales App. \r\n\r\nThere are two main ways to use Master Data:\r\n\r\n- [Directly from the storefront](#directly-from-the-storefront)\r\n- [With an external integration](#external-integrations)\r\n\r\n## Directly from the storefront\r\n\r\nWhen using Master Data within the storefront, consider the following:\r\n\r\n- Use the storefront host to query or store information to avoid issues related to Cross-origin resource sharing (CORS).\r\n- Use the relative path to avoid CORS issues.\r\n- Configure the JSON Schema of the Data Entity to specify which information should be public and which should not be.\r\n- Avoid creating query loops to prevent potential throttling issues or APIs being disabled due to security protection measures.\r\n- Never add authentication keys, such as `X-VTEX-API-AppKey` or `X-VTEX-API-AppToken`, via JavaScript as this could pose security risks.\r\n\r\n## External integrations\r\n\r\nWhen using Master Data to store data from an external integration, such as client data from another service, consider the following:\r\n\r\n- Use the host `{{accountName}}.vtexcommercestable.com.br`.\r\n- Use the authentication keys (`X-VTEX-API-AppKey` ou `X-VTEX-API-AppToken`).\r\n\r\n## Common parameters\r\n\r\n| Name | Description |\r\n| -------- | -------- |\r\n| `accountName` | Account name in VTEX License Manager. |\r\n| `name` | Data Entity name. |\r\n| `schema` | JSON Schema of a Data Entity. |\r\n| `id` | Identifier of a document. |\r\n| `X-VTEX-API-AppKey` | appKey. |\r\n| `X-VTEX-API-AppToken` | appToken. | \r\n\r\n## Index\r\n\r\n### Documents\r\n\r\n- `POST` [Create new document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#post-/api/dataentities/-dataEntityName-/documents)\r\n- `PATCH` [Create partial document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#patch-/api/dataentities/-dataEntityName-/documents)\r\n- `GET` [Get document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/documents/-id-)\r\n- `PUT` [Create document with custom ID or Update entire document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#put-/api/dataentities/-dataEntityName-/documents/-id-)\r\n- `PATCH` [Update partial document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#patch-/api/dataentities/-dataEntityName-/documents/-id-)\r\n- `DELETE` [Delete document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#delete-/api/dataentities/-dataEntityName-/documents/-id-)\r\n\r\n### Search\r\n\r\n- `GET` [Search documents](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/search)\r\n\r\n### Scroll\r\n\r\n- `GET` [Scroll documents](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/scroll)\r\n\r\n### Schemas\r\n\r\n- `GET` [Get schemas](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/schemas)\r\n- `GET` [Get schema by name](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/schemas/-schemaName-)\r\n- `PUT` [Save schema by name](https://developers.vtex.com/docs/api-reference/master-data-api-v2#put-/api/dataentities/-dataEntityName-/schemas/-schemaName-)\r\n- `DELETE` [Delete schema by name](https://developers.vtex.com/docs/api-reference/master-data-api-v2#delete-/api/dataentities/-dataEntityName-/schemas/-schemaName-)\r\n\r\n### Indices\r\n\r\n- `GET` [Get indices](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/indices)\r\n- `PUT` [Put indices](https://developers.vtex.com/docs/api-reference/master-data-api-v2#put-/api/dataentities/-dataEntityName-/indices)\r\n- `GET` [Get index by name](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/indices/-index_name-)\r\n- `DELETE` [Delete index by name](https://developers.vtex.com/docs/api-reference/master-data-api-v2#delete-/api/dataentities/-dataEntityName-/indices/-index_name-)\r\n\r\n### Clusters\r\n\r\n- `POST` [Validate document by clusters](https://developers.vtex.com/docs/api-reference/master-data-api-v2#post-/api/dataentities/-dataEntityName-/documents/-id-/clusters)\r\n\r\n### Versions\r\n\r\n- `GET` [List versions](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/documents/-id-/versions)\r\n- `GET` [Get version](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/documents/-id-/versions/-versionId-)\r\n- `PUT` [Put version](https://developers.vtex.com/docs/api-reference/master-data-api-v2#put-/api/dataentities/-dataEntityName-/documents/-id-/versions/-versionId-)", + "description": ">ℹ️ Master Data v2 is not compatible with data entities from previous versions, such as CL and AD.\r\n\r\n[Master Data](https://developers.vtex.com/docs/guides/master-data-introduction) is a secure, fast, scalable, and extensible solution that allows users to create their own entities, store data, and retrieve information directly from the storefront or external integrations.\r\n\r\nSeveral internal VTEX modules use Master Data as a data repository, including Orders and Sales App. \r\n\r\nThere are two main ways to use Master Data:\r\n\r\n- [Directly from the storefront](#directly-from-the-storefront)\r\n- [With an external integration](#external-integrations)\r\n\r\n## Directly from the storefront\r\n\r\nWhen using Master Data within the storefront, consider the following:\r\n\r\n- Use the storefront host to query or store information to avoid issues related to Cross-origin resource sharing (CORS).\r\n- Use the relative path to avoid CORS issues.\r\n- Configure the JSON Schema of the Data Entity to specify which information should be public and which should not be.\r\n- Avoid creating query loops to prevent potential throttling issues or APIs being disabled due to security protection measures.\r\n- Never add authentication keys, such as `X-VTEX-API-AppKey` or `X-VTEX-API-AppToken`, via JavaScript as this could pose security risks.\r\n\r\n## External integrations\r\n\r\nWhen using Master Data to store data from an external integration, such as client data from another service, consider the following:\r\n\r\n- Use the host `{{accountName}}.vtexcommercestable.com.br`.\r\n- Use the authentication keys (`X-VTEX-API-AppKey` ou `X-VTEX-API-AppToken`).\r\n\r\n## Common parameters\r\n\r\n| Name | Description |\r\n| -------- | -------- |\r\n| `accountName` | Account name in VTEX License Manager. |\r\n| `name` | Data Entity name. |\r\n| `schema` | JSON Schema of a Data Entity. |\r\n| `id` | Identifier of a document. |\r\n| `X-VTEX-API-AppKey` | appKey. |\r\n| `X-VTEX-API-AppToken` | appToken. | \r\n\r\n## Index\r\n\r\n### Documents\r\n\r\n- `POST` [Create new document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#post-/api/dataentities/-dataEntityName-/documents)\r\n- `PATCH` [Create partial document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#patch-/api/dataentities/-dataEntityName-/documents)\r\n- `GET` [Get document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/documents/-id-)\r\n- `PUT` [Create document with custom ID or Update entire document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#put-/api/dataentities/-dataEntityName-/documents/-id-)\r\n- `PATCH` [Update partial document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#patch-/api/dataentities/-dataEntityName-/documents/-id-)\r\n- `DELETE` [Delete document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#delete-/api/dataentities/-dataEntityName-/documents/-id-)\r\n\r\n### Search\r\n\r\n- `GET` [Search documents](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/search)\r\n\r\n### Scroll\r\n\r\n- `GET` [Scroll documents](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/scroll)\r\n\r\n### Personal Data\r\n\r\n- `POST` [Configure personal data fields](https://developers.vtex.com/docs/api-reference/master-data-api-v2#post-/api/dataentities/-dataEntityName-/personalData)\r\n\r\n### Schemas\r\n\r\n- `GET` [Get schemas](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/schemas)\r\n- `GET` [Get schema by name](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/schemas/-schemaName-)\r\n- `PUT` [Save schema by name](https://developers.vtex.com/docs/api-reference/master-data-api-v2#put-/api/dataentities/-dataEntityName-/schemas/-schemaName-)\r\n- `DELETE` [Delete schema by name](https://developers.vtex.com/docs/api-reference/master-data-api-v2#delete-/api/dataentities/-dataEntityName-/schemas/-schemaName-)\r\n\r\n### Indices\r\n\r\n- `GET` [Get indices](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/indices)\r\n- `PUT` [Put indices](https://developers.vtex.com/docs/api-reference/master-data-api-v2#put-/api/dataentities/-dataEntityName-/indices)\r\n- `GET` [Get index by name](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/indices/-index_name-)\r\n- `DELETE` [Delete index by name](https://developers.vtex.com/docs/api-reference/master-data-api-v2#delete-/api/dataentities/-dataEntityName-/indices/-index_name-)\r\n\r\n### Clusters\r\n\r\n- `POST` [Validate document by clusters](https://developers.vtex.com/docs/api-reference/master-data-api-v2#post-/api/dataentities/-dataEntityName-/documents/-id-/clusters)\r\n\r\n### Versions\r\n\r\n- `GET` [List versions](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/documents/-id-/versions)\r\n- `GET` [Get version](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/documents/-id-/versions/-versionId-)\r\n- `PUT` [Put version](https://developers.vtex.com/docs/api-reference/master-data-api-v2#put-/api/dataentities/-dataEntityName-/documents/-id-/versions/-versionId-)", "contact": {}, "version": "1.0" }, @@ -46,6 +46,9 @@ }, { "$ref": "#/components/parameters/_schema" + }, + { + "$ref": "#/components/parameters/dataSubject" } ], "requestBody": { @@ -122,6 +125,9 @@ }, { "$ref": "#/components/parameters/Accept" + }, + { + "$ref": "#/components/parameters/dataSubject" } ], "requestBody": { @@ -165,7 +171,7 @@ "Documents" ], "summary": "Get document", - "description": "Retrieves a document by ID.\n\r\n\r>ℹ️ Assign the `_fields` parameter in the query string to retrieve the desired fields. If you want to return all the fields use `_fields=_all`.\r\n\r\n>ℹ️ Fields flagged as PII (`v-pii`) in the data entity schema are returned with masked values by default. To retrieve the original values, add the `unmasked=true` query parameter.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", + "description": "Retrieves a document by ID.\n\r\n\r>ℹ️ Assign the `_fields` parameter in the query string to retrieve the desired fields. If you want to return all the fields use `_fields=_all`.\r\n\r\n>ℹ️ Fields [configured as personal data](https://developers.vtex.com/docs/api-reference/master-data-api-v2#post-/api/dataentities/-dataEntityName-/personalData) are returned with masked values by default. To retrieve the original values, add the `openData=true` query parameter.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Getdocument", "parameters": [ { @@ -187,7 +193,7 @@ "$ref": "#/components/parameters/_schema" }, { - "$ref": "#/components/parameters/unmasked" + "$ref": "#/components/parameters/openData" } ], "responses": { @@ -240,6 +246,9 @@ "type": "string", "example": "Newsletter-b818cbda-e489-11e6-94f4-0ac138d2d42e" } + }, + { + "$ref": "#/components/parameters/dataSubject" } ], "requestBody": { @@ -298,6 +307,9 @@ }, { "$ref": "#/components/parameters/id" + }, + { + "$ref": "#/components/parameters/dataSubject" } ], "requestBody": { @@ -356,7 +368,7 @@ "Search" ], "summary": "Search documents", - "description": "Retrieves Master Data v2 documents' information, while choosing which fields will be returned and filtering documents by specific fields.\r\n\r\n> The response header `REST-Content-Range` indicates the total amount of results for that specific search. For example, it may return `resources 0-100/136108`, which indicates it has returned the first 100 results out of a total of 136108.\r\n\r\nBelow you can see some query examples and learn more about each query parameter.\n\r\n\rLearn more about [Pagination in the Master Data API](https://developers.vtex.com/docs/guides/pagination-in-the-master-data-api).\r\n\r\n>ℹ️ Fields flagged as PII (`v-pii`) in the data entity schema are returned with masked values by default. To retrieve the original values, add the `unmasked=true` query parameter.\r\n\r\n>⚠️ Avoid sending too many requests with wildcards (`*`) in the search parameters or that use the `keyword` parameter. This may lead to this endpoint being temporarily blocked for your account. If this happens you will receive an error with status code `503`.\r\n\r\n## Query examples\r\n\r\n| **Query Type** | **Example** |\r\n|-|-|\r\n| **Simple filter** | `\/dataentities\/Newsletter\/search?email=my@email.com` |\r\n| **Complex filter** | `\/dataentities\/Newsletter\/search?_where=(firstName=Jon OR lastName=Smith) OR (createdIn between 2001-01-01 AND 2016-01-01)` |\r\n| **Date range** | `\/dataentities\/Newsletter\/search?_where=createdIn between 2001-01-01 AND 2016-01-01` |\r\n| **Range numeric fields** | `\/dataentities\/Newsletter\/search?_where=age between 18 AND 25` |\r\n| **Partial filter** | `\/dataentities\/Newsletter\/search?firstName=*Maria*` |\r\n| **Filter for null values** | `\/dataentities\/Newsletter\/search?_where=firstName is null` |\r\n| **Filter for non-null values** | `\/dataentities\/Newsletter\/search?_where=firstName is not null` |\r\n| **Filter for difference** | `\/dataentities\/Newsletter\/search?_where=firstName<>maria` |\r\n| **Filter greater than** | `\/dataentities\/Newsletter\/search?_where=number>5` |\r\n| **Filter less than** | `\/dataentities\/Newsletter\/search?_where=date<2001-01-01` |\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", + "description": "Retrieves Master Data v2 documents' information, while choosing which fields will be returned and filtering documents by specific fields.\r\n\r\n> The response header `REST-Content-Range` indicates the total amount of results for that specific search. For example, it may return `resources 0-100/136108`, which indicates it has returned the first 100 results out of a total of 136108.\r\n\r\nBelow you can see some query examples and learn more about each query parameter.\n\r\n\rLearn more about [Pagination in the Master Data API](https://developers.vtex.com/docs/guides/pagination-in-the-master-data-api).\r\n\r\n>ℹ️ Fields [configured as personal data](https://developers.vtex.com/docs/api-reference/master-data-api-v2#post-/api/dataentities/-dataEntityName-/personalData) are returned with masked values by default. To retrieve the original values, add the `openData=true` query parameter. Personal data fields only support exact matching when used as search filters.\r\n\r\n>⚠️ Avoid sending too many requests with wildcards (`*`) in the search parameters or that use the `keyword` parameter. This may lead to this endpoint being temporarily blocked for your account. If this happens you will receive an error with status code `503`.\r\n\r\n## Query examples\r\n\r\n| **Query Type** | **Example** |\r\n|-|-|\r\n| **Simple filter** | `\/dataentities\/Newsletter\/search?email=my@email.com` |\r\n| **Complex filter** | `\/dataentities\/Newsletter\/search?_where=(firstName=Jon OR lastName=Smith) OR (createdIn between 2001-01-01 AND 2016-01-01)` |\r\n| **Date range** | `\/dataentities\/Newsletter\/search?_where=createdIn between 2001-01-01 AND 2016-01-01` |\r\n| **Range numeric fields** | `\/dataentities\/Newsletter\/search?_where=age between 18 AND 25` |\r\n| **Partial filter** | `\/dataentities\/Newsletter\/search?firstName=*Maria*` |\r\n| **Filter for null values** | `\/dataentities\/Newsletter\/search?_where=firstName is null` |\r\n| **Filter for non-null values** | `\/dataentities\/Newsletter\/search?_where=firstName is not null` |\r\n| **Filter for difference** | `\/dataentities\/Newsletter\/search?_where=firstName<>maria` |\r\n| **Filter greater than** | `\/dataentities\/Newsletter\/search?_where=number>5` |\r\n| **Filter less than** | `\/dataentities\/Newsletter\/search?_where=date<2001-01-01` |\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Searchdocuments", "parameters": [ { @@ -384,7 +396,7 @@ "$ref": "#/components/parameters/_sort" }, { - "$ref": "#/components/parameters/unmasked" + "$ref": "#/components/parameters/openData" } ], "responses": { @@ -472,7 +484,7 @@ "Scroll" ], "summary": "Scroll documents", - "description": "Returns a list of documents according to query parameter filters. If you need to query the entire database, or your collection is over 10000 documents, use this endpoint.\r\n\r\nIn the first request, the `X-VTEX-MD-TOKEN` token will be obtained in the response header. This token must be passed to the next request in the `_token` query string parameter. The token expires after 20 minutes of inactivity, and each request made with the token during this time resets the expiration timer.\r\n\r\nAfter the token is obtained, it is no longer necessary to send the filter or document size per page parameters. You only need to resend the token until the document collection is empty.\r\n\r\nFirst request:\r\n```\r\n/dataentities/Newsletter/scroll?isCluster=true&_size=250&_fields=email,firstName\r\n```\r\n\r\nRetrieve the token in the header `X-VTEX-MD-TOKEN` from the first request's response and use it to make the following requests.\r\n\r\nSubsequent requests:\r\n```\r\n/dataentities/Newsletter/scroll?_token={tokenValue}\r\n```\n\r\n\rLearn more about [Pagination in the Master Data API](https://developers.vtex.com/docs/guides/pagination-in-the-master-data-api).\r\n\r\n>ℹ️ Fields flagged as PII (`v-pii`) in the data entity schema are returned with masked values by default. To retrieve the original values, add the `unmasked=true` query parameter.\r\n\r\n>⚠️ Avoid sending too many requests with wildcards (`*`) in the search parameters or using the `keyword` parameter. This may lead to this endpoint being temporarily blocked for your account. If this happens you will receive an error with status code `429`.\r\n\r\n## Query examples\r\n\r\n| **Query Type** | **Example** |\r\n|-|-|\r\n| **Simple filter** | `\/dataentities\/Newsletter\/scroll?email=my@email.com` |\r\n| **Complex filter** | `\/dataentities\/Newsletter\/scroll?_where=(firstName=Jon OR lastName=Smith) OR (createdIn between 2001-01-01 AND 2016-01-01)` |\r\n| **Date range** | `\/dataentities\/Newsletter\/scroll?_where=createdIn between 2001-01-01 AND 2016-01-01` |\r\n| **Range numeric fields** | `\/dataentities\/Newsletter\/scroll?_where=age between 18 AND 25` |\r\n| **Partial filter** | `\/dataentities\/Newsletter\/scroll?firstName=*Maria*` |\r\n| **Filter for null values** | `\/dataentities\/Newsletter\/scroll?_where=firstName is null` |\r\n| **Filter for non-null values** | `\/dataentities\/Newsletter\/scroll?_where=firstName is not null` |\r\n| **Filter for difference** | `\/dataentities\/Newsletter\/scroll?_where=firstName<>maria` |\r\n| **Filter greater than** | `\/dataentities\/Newsletter\/scroll?_where=number>5` |\r\n| **Filter less than** | `\/dataentities\/Newsletter\/scroll?_where=date<2001-01-01` |\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", + "description": "Returns a list of documents according to query parameter filters. If you need to query the entire database, or your collection is over 10000 documents, use this endpoint.\r\n\r\nIn the first request, the `X-VTEX-MD-TOKEN` token will be obtained in the response header. This token must be passed to the next request in the `_token` query string parameter. The token expires after 20 minutes of inactivity, and each request made with the token during this time resets the expiration timer.\r\n\r\nAfter the token is obtained, it is no longer necessary to send the filter or document size per page parameters. You only need to resend the token until the document collection is empty.\r\n\r\nFirst request:\r\n```\r\n/dataentities/Newsletter/scroll?isCluster=true&_size=250&_fields=email,firstName\r\n```\r\n\r\nRetrieve the token in the header `X-VTEX-MD-TOKEN` from the first request's response and use it to make the following requests.\r\n\r\nSubsequent requests:\r\n```\r\n/dataentities/Newsletter/scroll?_token={tokenValue}\r\n```\n\r\n\rLearn more about [Pagination in the Master Data API](https://developers.vtex.com/docs/guides/pagination-in-the-master-data-api).\r\n\r\n>ℹ️ Fields [configured as personal data](https://developers.vtex.com/docs/api-reference/master-data-api-v2#post-/api/dataentities/-dataEntityName-/personalData) are returned with masked values by default. To retrieve the original values, add the `openData=true` query parameter.\r\n\r\n>⚠️ Avoid sending too many requests with wildcards (`*`) in the search parameters or using the `keyword` parameter. This may lead to this endpoint being temporarily blocked for your account. If this happens you will receive an error with status code `429`.\r\n\r\n## Query examples\r\n\r\n| **Query Type** | **Example** |\r\n|-|-|\r\n| **Simple filter** | `\/dataentities\/Newsletter\/scroll?email=my@email.com` |\r\n| **Complex filter** | `\/dataentities\/Newsletter\/scroll?_where=(firstName=Jon OR lastName=Smith) OR (createdIn between 2001-01-01 AND 2016-01-01)` |\r\n| **Date range** | `\/dataentities\/Newsletter\/scroll?_where=createdIn between 2001-01-01 AND 2016-01-01` |\r\n| **Range numeric fields** | `\/dataentities\/Newsletter\/scroll?_where=age between 18 AND 25` |\r\n| **Partial filter** | `\/dataentities\/Newsletter\/scroll?firstName=*Maria*` |\r\n| **Filter for null values** | `\/dataentities\/Newsletter\/scroll?_where=firstName is null` |\r\n| **Filter for non-null values** | `\/dataentities\/Newsletter\/scroll?_where=firstName is not null` |\r\n| **Filter for difference** | `\/dataentities\/Newsletter\/scroll?_where=firstName<>maria` |\r\n| **Filter greater than** | `\/dataentities\/Newsletter\/scroll?_where=number>5` |\r\n| **Filter less than** | `\/dataentities\/Newsletter\/scroll?_where=date<2001-01-01` |\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Scrolldocuments", "parameters": [ { @@ -503,7 +515,7 @@ "$ref": "#/components/parameters/_sort" }, { - "$ref": "#/components/parameters/unmasked" + "$ref": "#/components/parameters/openData" } ], "responses": { @@ -570,6 +582,55 @@ "deprecated": false } }, + "/api/dataentities/{dataEntityName}/personalData": { + "post": { + "tags": [ + "Personal Data" + ], + "summary": "Configure personal data fields", + "description": "Defines which fields of a data entity contain personal data. Fields configured as personal data are stored separately with encryption and special data residency, and are returned masked by default when retrieving documents. You can optionally indicate which field identifies the data subject (owner of the data), used for compliance with data subject requests such as the right to be forgotten.\r\n\r\n>ℹ️ Personal data configuration is set at the data entity level, not within individual schemas. This avoids conflicts when multiple schemas coexist for the same data entity.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", + "operationId": "ConfigurePersonalDataFields", + "parameters": [ + { + "$ref": "#/components/parameters/Content-Type" + }, + { + "$ref": "#/components/parameters/Accept" + }, + { + "$ref": "#/components/parameters/dataEntityName" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PersonalDataRequest" + }, + "example": { + "fields": [ + "email" + ], + "data_subject_field": "email" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "OK" + }, + "400": { + "description": "Bad Request" + }, + "403": { + "description": "Forbidden" + } + }, + "deprecated": false + } + }, "/api/dataentities/{dataEntityName}/schemas": { "get": { "tags": [ @@ -662,7 +723,7 @@ "Schemas" ], "summary": "Save schema by name", - "description": "Creates or edits a data entity schema. Learn more about [Master Data schemas](https://developers.vtex.com/vtex-rest-api/docs/master-data-schema-lifecycle).\r\n\r\n> Note that if you send a `schemaName` that does not exist for that data entity, this request will create it.\r\n\r\nThis request can also be used to [create or edit Master Data v2 triggers](https://developers.vtex.com/vtex-rest-api/docs/setting-up-triggers-in-master-data-v2).\r\n\r\n> Each Master Data v2 data entity can have up to 60 schemas.\r\n\r\n## Indexing fields for search, scroll and sort\r\n\r\nTo filter or sort by a field in [Search documents](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/search) or [Scroll documents](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/scroll), add that field to the `v-indexed` array in the schema. This is the schema-level index (separate from the [indices](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/indices) endpoint).\r\n\r\n- `v-indexed`: Array of property names that Master Data v2 must index for `/search`, `/scroll`, and `_sort`. Use it whenever you want to use `_where`, `_sort`, or range filters (e.g. `_where=postalCode between 10000 AND 20000`) on that field. Indexing runs asynchronously after the schema is saved.\r\n- `filterable` and `searchable`: Apply to the UI (e.g. Master Data v1/CRM-style behavior). They do **not** create the index used by `/search`; only `v-indexed` does.\r\n\r\n**Example request body with `v-indexed`:**\r\n\r\n```json\r\n{\r\n \"properties\": {\r\n \"skuId\": { \"type\": \"string\" },\r\n \"postalCode\": { \"type\": \"string\" }\r\n },\r\n \"v-indexed\": [\"postalCode\"]\r\n}\r\n```\r\n\r\n> ℹ️ Use `v-indexed` when you need fields to be filterable/sortable in `/search`. Use the [/indices](https://developers.vtex.com/docs/api-reference/master-data-api-v2#put-/api/dataentities/-dataEntityName-/indices) endpoint when you need entity-level uniqueness, composite keys, or relationships between entities.\r\n\r\n## Flagging fields as PII\r\n\r\nTo flag fields that contain personally identifiable information (PII), add those field names to the `v-pii` array in the schema. Fields listed in `v-pii` are handled according to data protection best practices: their values are stored securely and returned masked by default when retrieving documents.\r\n\r\nTo retrieve the original (unmasked) values of PII fields, pass the query parameter `unmasked=true` in [Get document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/documents/-id-), [Search documents](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/search), or [Scroll documents](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/scroll).\r\n\r\n**Example request body with `v-pii`:**\r\n\r\n```json\r\n{\r\n \"properties\": {\r\n \"email\": { \"type\": \"string\" },\r\n \"firstName\": { \"type\": \"string\" },\r\n \"document\": { \"type\": \"string\" }\r\n },\r\n \"v-pii\": [\"email\", \"document\"]\r\n}\r\n```\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", + "description": "Creates or edits a data entity schema. Learn more about [Master Data schemas](https://developers.vtex.com/vtex-rest-api/docs/master-data-schema-lifecycle).\r\n\r\n> Note that if you send a `schemaName` that does not exist for that data entity, this request will create it.\r\n\r\nThis request can also be used to [create or edit Master Data v2 triggers](https://developers.vtex.com/vtex-rest-api/docs/setting-up-triggers-in-master-data-v2).\r\n\r\n> Each Master Data v2 data entity can have up to 60 schemas.\r\n\r\n## Indexing fields for search, scroll and sort\r\n\r\nTo filter or sort by a field in [Search documents](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/search) or [Scroll documents](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/scroll), add that field to the `v-indexed` array in the schema. This is the schema-level index (separate from the [indices](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/indices) endpoint).\r\n\r\n- `v-indexed`: Array of property names that Master Data v2 must index for `/search`, `/scroll`, and `_sort`. Use it whenever you want to use `_where`, `_sort`, or range filters (e.g. `_where=postalCode between 10000 AND 20000`) on that field. Indexing runs asynchronously after the schema is saved.\r\n- `filterable` and `searchable`: Apply to the UI (e.g. Master Data v1/CRM-style behavior). They do **not** create the index used by `/search`; only `v-indexed` does.\r\n\r\n**Example request body with `v-indexed`:**\r\n\r\n```json\r\n{\r\n \"properties\": {\r\n \"skuId\": { \"type\": \"string\" },\r\n \"postalCode\": { \"type\": \"string\" }\r\n },\r\n \"v-indexed\": [\"postalCode\"]\r\n}\r\n```\r\n\r\n> ℹ️ Use `v-indexed` when you need fields to be filterable/sortable in `/search`. Use the [/indices](https://developers.vtex.com/docs/api-reference/master-data-api-v2#put-/api/dataentities/-dataEntityName-/indices) endpoint when you need entity-level uniqueness, composite keys, or relationships between entities.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Saveschemabyname", "parameters": [ { @@ -673,7 +734,7 @@ } ], "requestBody": { - "description": "JSON Schema of the data entity. Include `v-indexed` with an array of property names when you will filter or sort by those fields in /search or /scroll. Include `v-pii` with an array of property names to flag fields as personally identifiable information (PII), which will be masked by default on retrieval.", + "description": "JSON Schema of the data entity. Include `v-indexed` with an array of property names when you will filter or sort by those fields in /search or /scroll.", "content": { "application/json": { "schema": { @@ -705,26 +766,6 @@ "postalCode" ] } - }, - "withVPii": { - "summary": "Schema with v-pii for PII masking", - "value": { - "properties": { - "email": { - "type": "string" - }, - "firstName": { - "type": "string" - }, - "document": { - "type": "string" - } - }, - "v-pii": [ - "email", - "document" - ] - } } } } @@ -1263,6 +1304,27 @@ } }, "schemas": { + "PersonalDataRequest": { + "title": "PersonalDataRequest", + "required": [ + "fields" + ], + "type": "object", + "description": "Configuration of personal data fields for a data entity.", + "properties": { + "fields": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Names of fields that contain personal data. These fields are stored with encryption and special data residency, and are returned masked by default when retrieving documents." + }, + "data_subject_field": { + "type": "string", + "description": "Name of the field that identifies the data subject (owner of the personal data). Used for compliance with data subject requests such as the right to be forgotten. Can be overridden per document by the `dataSubject` query parameter on write endpoints." + } + } + }, "DocumentRequest": { "title": "DocumentRequest", "type": "object", @@ -1304,7 +1366,7 @@ "properties" ], "type": "object", - "description": "JSON Schema of the data entity. Add `v-indexed` with an array of property names to make those fields filterable and sortable in /search and /scroll. Add `v-pii` with an array of property names to flag fields as PII, which will be masked by default on retrieval.", + "description": "JSON Schema of the data entity. Add `v-indexed` with an array of property names to make those fields filterable and sortable in /search and /scroll.", "properties": { "properties": { "type": "object", @@ -1339,13 +1401,6 @@ "type": "string" }, "description": "Names of properties to index for /search, /scroll, and _sort. Required for reliable filtering (e.g. _where=field=value) and sorting (_sort=field ASC). Indexing is asynchronous after schema save." - }, - "v-pii": { - "type": "array", - "items": { - "type": "string" - }, - "description": "Names of properties that contain personally identifiable information (PII). Fields listed here are handled according to data protection best practices and returned with masked values by default. To retrieve original values, use the `unmasked=true` query parameter on document retrieval endpoints." } } }, @@ -1392,13 +1447,6 @@ } } } - }, - "v-pii": { - "type": "array", - "items": { - "type": "string" - }, - "description": "Names of properties flagged as personally identifiable information (PII)." } } } @@ -1805,10 +1853,21 @@ "default": 100 } }, - "unmasked": { - "name": "unmasked", + "dataSubject": { + "name": "dataSubject", "in": "query", - "description": "When set to `true`, fields flagged as PII (`v-pii`) in the data entity schema are returned with their original values. By default (`false`), PII fields are returned with masked values.", + "description": "Identifier of the owner (data subject) of the personal data in this document, used for compliance with data subject requests (e.g., right to be forgotten). If this parameter is present, it overrides any `data_subject_field` configured via the [Configure personal data fields](https://developers.vtex.com/docs/api-reference/master-data-api-v2#post-/api/dataentities/-dataEntityName-/personalData) endpoint. Only required when the data entity has personal data fields configured.", + "required": false, + "style": "form", + "schema": { + "type": "string", + "example": "john@example.com" + } + }, + "openData": { + "name": "openData", + "in": "query", + "description": "When set to `true`, fields configured as personal data are returned with their original values. By default (`false`), personal data fields are returned with masked values (e.g., `j***@****.com`).", "required": false, "style": "form", "schema": { @@ -1828,6 +1887,9 @@ { "name": "Scroll" }, + { + "name": "Personal Data" + }, { "name": "Schemas" }, From d1368b8e6291fece9c034976db308de2adc60dea Mon Sep 17 00:00:00 2001 From: Pedro Antunes <47991446+PedroAntunesCosta@users.noreply.github.com> Date: Thu, 23 Apr 2026 13:37:29 -0300 Subject: [PATCH 4/8] fix: align personal data params with PRD for Master Data API v2 Rename openData to unmasked, add audited reason parameter for reads, remove legacy dataSubject query param from writes, and require data_subject_field in personal data configuration schema. --- VTEX - Master Data API - v2.json | 58 +++++++++++++++----------------- 1 file changed, 28 insertions(+), 30 deletions(-) diff --git a/VTEX - Master Data API - v2.json b/VTEX - Master Data API - v2.json index 278e773c7..793304559 100644 --- a/VTEX - Master Data API - v2.json +++ b/VTEX - Master Data API - v2.json @@ -46,9 +46,6 @@ }, { "$ref": "#/components/parameters/_schema" - }, - { - "$ref": "#/components/parameters/dataSubject" } ], "requestBody": { @@ -125,9 +122,6 @@ }, { "$ref": "#/components/parameters/Accept" - }, - { - "$ref": "#/components/parameters/dataSubject" } ], "requestBody": { @@ -171,7 +165,7 @@ "Documents" ], "summary": "Get document", - "description": "Retrieves a document by ID.\n\r\n\r>ℹ️ Assign the `_fields` parameter in the query string to retrieve the desired fields. If you want to return all the fields use `_fields=_all`.\r\n\r\n>ℹ️ Fields [configured as personal data](https://developers.vtex.com/docs/api-reference/master-data-api-v2#post-/api/dataentities/-dataEntityName-/personalData) are returned with masked values by default. To retrieve the original values, add the `openData=true` query parameter.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", + "description": "Retrieves a document by ID.\n\r\n\r>ℹ️ Assign the `_fields` parameter in the query string to retrieve the desired fields. If you want to return all the fields use `_fields=_all`.\r\n\r\n>ℹ️ Fields [configured as personal data](https://developers.vtex.com/docs/api-reference/master-data-api-v2#post-/api/dataentities/-dataEntityName-/personalData) are returned with masked values by default. To retrieve the original values, add the `unmasked=true` query parameter (a `reason` is also required).\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Getdocument", "parameters": [ { @@ -193,7 +187,10 @@ "$ref": "#/components/parameters/_schema" }, { - "$ref": "#/components/parameters/openData" + "$ref": "#/components/parameters/unmasked" + }, + { + "$ref": "#/components/parameters/reason" } ], "responses": { @@ -246,9 +243,6 @@ "type": "string", "example": "Newsletter-b818cbda-e489-11e6-94f4-0ac138d2d42e" } - }, - { - "$ref": "#/components/parameters/dataSubject" } ], "requestBody": { @@ -307,9 +301,6 @@ }, { "$ref": "#/components/parameters/id" - }, - { - "$ref": "#/components/parameters/dataSubject" } ], "requestBody": { @@ -368,7 +359,7 @@ "Search" ], "summary": "Search documents", - "description": "Retrieves Master Data v2 documents' information, while choosing which fields will be returned and filtering documents by specific fields.\r\n\r\n> The response header `REST-Content-Range` indicates the total amount of results for that specific search. For example, it may return `resources 0-100/136108`, which indicates it has returned the first 100 results out of a total of 136108.\r\n\r\nBelow you can see some query examples and learn more about each query parameter.\n\r\n\rLearn more about [Pagination in the Master Data API](https://developers.vtex.com/docs/guides/pagination-in-the-master-data-api).\r\n\r\n>ℹ️ Fields [configured as personal data](https://developers.vtex.com/docs/api-reference/master-data-api-v2#post-/api/dataentities/-dataEntityName-/personalData) are returned with masked values by default. To retrieve the original values, add the `openData=true` query parameter. Personal data fields only support exact matching when used as search filters.\r\n\r\n>⚠️ Avoid sending too many requests with wildcards (`*`) in the search parameters or that use the `keyword` parameter. This may lead to this endpoint being temporarily blocked for your account. If this happens you will receive an error with status code `503`.\r\n\r\n## Query examples\r\n\r\n| **Query Type** | **Example** |\r\n|-|-|\r\n| **Simple filter** | `\/dataentities\/Newsletter\/search?email=my@email.com` |\r\n| **Complex filter** | `\/dataentities\/Newsletter\/search?_where=(firstName=Jon OR lastName=Smith) OR (createdIn between 2001-01-01 AND 2016-01-01)` |\r\n| **Date range** | `\/dataentities\/Newsletter\/search?_where=createdIn between 2001-01-01 AND 2016-01-01` |\r\n| **Range numeric fields** | `\/dataentities\/Newsletter\/search?_where=age between 18 AND 25` |\r\n| **Partial filter** | `\/dataentities\/Newsletter\/search?firstName=*Maria*` |\r\n| **Filter for null values** | `\/dataentities\/Newsletter\/search?_where=firstName is null` |\r\n| **Filter for non-null values** | `\/dataentities\/Newsletter\/search?_where=firstName is not null` |\r\n| **Filter for difference** | `\/dataentities\/Newsletter\/search?_where=firstName<>maria` |\r\n| **Filter greater than** | `\/dataentities\/Newsletter\/search?_where=number>5` |\r\n| **Filter less than** | `\/dataentities\/Newsletter\/search?_where=date<2001-01-01` |\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", + "description": "Retrieves Master Data v2 documents' information, while choosing which fields will be returned and filtering documents by specific fields.\r\n\r\n> The response header `REST-Content-Range` indicates the total amount of results for that specific search. For example, it may return `resources 0-100/136108`, which indicates it has returned the first 100 results out of a total of 136108.\r\n\r\nBelow you can see some query examples and learn more about each query parameter.\n\r\n\rLearn more about [Pagination in the Master Data API](https://developers.vtex.com/docs/guides/pagination-in-the-master-data-api).\r\n\r\n>ℹ️ Fields [configured as personal data](https://developers.vtex.com/docs/api-reference/master-data-api-v2#post-/api/dataentities/-dataEntityName-/personalData) are returned with masked values by default. To retrieve the original values, add the `unmasked=true` query parameter (a `reason` is also required). Personal data fields only support exact matching when used as search filters.\r\n\r\n>⚠️ Avoid sending too many requests with wildcards (`*`) in the search parameters or that use the `keyword` parameter. This may lead to this endpoint being temporarily blocked for your account. If this happens you will receive an error with status code `503`.\r\n\r\n## Query examples\r\n\r\n| **Query Type** | **Example** |\r\n|-|-|\r\n| **Simple filter** | `\/dataentities\/Newsletter\/search?email=my@email.com` |\r\n| **Complex filter** | `\/dataentities\/Newsletter\/search?_where=(firstName=Jon OR lastName=Smith) OR (createdIn between 2001-01-01 AND 2016-01-01)` |\r\n| **Date range** | `\/dataentities\/Newsletter\/search?_where=createdIn between 2001-01-01 AND 2016-01-01` |\r\n| **Range numeric fields** | `\/dataentities\/Newsletter\/search?_where=age between 18 AND 25` |\r\n| **Partial filter** | `\/dataentities\/Newsletter\/search?firstName=*Maria*` |\r\n| **Filter for null values** | `\/dataentities\/Newsletter\/search?_where=firstName is null` |\r\n| **Filter for non-null values** | `\/dataentities\/Newsletter\/search?_where=firstName is not null` |\r\n| **Filter for difference** | `\/dataentities\/Newsletter\/search?_where=firstName<>maria` |\r\n| **Filter greater than** | `\/dataentities\/Newsletter\/search?_where=number>5` |\r\n| **Filter less than** | `\/dataentities\/Newsletter\/search?_where=date<2001-01-01` |\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Searchdocuments", "parameters": [ { @@ -396,7 +387,10 @@ "$ref": "#/components/parameters/_sort" }, { - "$ref": "#/components/parameters/openData" + "$ref": "#/components/parameters/unmasked" + }, + { + "$ref": "#/components/parameters/reason" } ], "responses": { @@ -484,7 +478,7 @@ "Scroll" ], "summary": "Scroll documents", - "description": "Returns a list of documents according to query parameter filters. If you need to query the entire database, or your collection is over 10000 documents, use this endpoint.\r\n\r\nIn the first request, the `X-VTEX-MD-TOKEN` token will be obtained in the response header. This token must be passed to the next request in the `_token` query string parameter. The token expires after 20 minutes of inactivity, and each request made with the token during this time resets the expiration timer.\r\n\r\nAfter the token is obtained, it is no longer necessary to send the filter or document size per page parameters. You only need to resend the token until the document collection is empty.\r\n\r\nFirst request:\r\n```\r\n/dataentities/Newsletter/scroll?isCluster=true&_size=250&_fields=email,firstName\r\n```\r\n\r\nRetrieve the token in the header `X-VTEX-MD-TOKEN` from the first request's response and use it to make the following requests.\r\n\r\nSubsequent requests:\r\n```\r\n/dataentities/Newsletter/scroll?_token={tokenValue}\r\n```\n\r\n\rLearn more about [Pagination in the Master Data API](https://developers.vtex.com/docs/guides/pagination-in-the-master-data-api).\r\n\r\n>ℹ️ Fields [configured as personal data](https://developers.vtex.com/docs/api-reference/master-data-api-v2#post-/api/dataentities/-dataEntityName-/personalData) are returned with masked values by default. To retrieve the original values, add the `openData=true` query parameter.\r\n\r\n>⚠️ Avoid sending too many requests with wildcards (`*`) in the search parameters or using the `keyword` parameter. This may lead to this endpoint being temporarily blocked for your account. If this happens you will receive an error with status code `429`.\r\n\r\n## Query examples\r\n\r\n| **Query Type** | **Example** |\r\n|-|-|\r\n| **Simple filter** | `\/dataentities\/Newsletter\/scroll?email=my@email.com` |\r\n| **Complex filter** | `\/dataentities\/Newsletter\/scroll?_where=(firstName=Jon OR lastName=Smith) OR (createdIn between 2001-01-01 AND 2016-01-01)` |\r\n| **Date range** | `\/dataentities\/Newsletter\/scroll?_where=createdIn between 2001-01-01 AND 2016-01-01` |\r\n| **Range numeric fields** | `\/dataentities\/Newsletter\/scroll?_where=age between 18 AND 25` |\r\n| **Partial filter** | `\/dataentities\/Newsletter\/scroll?firstName=*Maria*` |\r\n| **Filter for null values** | `\/dataentities\/Newsletter\/scroll?_where=firstName is null` |\r\n| **Filter for non-null values** | `\/dataentities\/Newsletter\/scroll?_where=firstName is not null` |\r\n| **Filter for difference** | `\/dataentities\/Newsletter\/scroll?_where=firstName<>maria` |\r\n| **Filter greater than** | `\/dataentities\/Newsletter\/scroll?_where=number>5` |\r\n| **Filter less than** | `\/dataentities\/Newsletter\/scroll?_where=date<2001-01-01` |\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", + "description": "Returns a list of documents according to query parameter filters. If you need to query the entire database, or your collection is over 10000 documents, use this endpoint.\r\n\r\nIn the first request, the `X-VTEX-MD-TOKEN` token will be obtained in the response header. This token must be passed to the next request in the `_token` query string parameter. The token expires after 20 minutes of inactivity, and each request made with the token during this time resets the expiration timer.\r\n\r\nAfter the token is obtained, it is no longer necessary to send the filter or document size per page parameters. You only need to resend the token until the document collection is empty.\r\n\r\nFirst request:\r\n```\r\n/dataentities/Newsletter/scroll?isCluster=true&_size=250&_fields=email,firstName\r\n```\r\n\r\nRetrieve the token in the header `X-VTEX-MD-TOKEN` from the first request's response and use it to make the following requests.\r\n\r\nSubsequent requests:\r\n```\r\n/dataentities/Newsletter/scroll?_token={tokenValue}\r\n```\n\r\n\rLearn more about [Pagination in the Master Data API](https://developers.vtex.com/docs/guides/pagination-in-the-master-data-api).\r\n\r\n>ℹ️ Fields [configured as personal data](https://developers.vtex.com/docs/api-reference/master-data-api-v2#post-/api/dataentities/-dataEntityName-/personalData) are returned with masked values by default. To retrieve the original values, add the `unmasked=true` query parameter (a `reason` is also required).\r\n\r\n>⚠️ Avoid sending too many requests with wildcards (`*`) in the search parameters or using the `keyword` parameter. This may lead to this endpoint being temporarily blocked for your account. If this happens you will receive an error with status code `429`.\r\n\r\n## Query examples\r\n\r\n| **Query Type** | **Example** |\r\n|-|-|\r\n| **Simple filter** | `\/dataentities\/Newsletter\/scroll?email=my@email.com` |\r\n| **Complex filter** | `\/dataentities\/Newsletter\/scroll?_where=(firstName=Jon OR lastName=Smith) OR (createdIn between 2001-01-01 AND 2016-01-01)` |\r\n| **Date range** | `\/dataentities\/Newsletter\/scroll?_where=createdIn between 2001-01-01 AND 2016-01-01` |\r\n| **Range numeric fields** | `\/dataentities\/Newsletter\/scroll?_where=age between 18 AND 25` |\r\n| **Partial filter** | `\/dataentities\/Newsletter\/scroll?firstName=*Maria*` |\r\n| **Filter for null values** | `\/dataentities\/Newsletter\/scroll?_where=firstName is null` |\r\n| **Filter for non-null values** | `\/dataentities\/Newsletter\/scroll?_where=firstName is not null` |\r\n| **Filter for difference** | `\/dataentities\/Newsletter\/scroll?_where=firstName<>maria` |\r\n| **Filter greater than** | `\/dataentities\/Newsletter\/scroll?_where=number>5` |\r\n| **Filter less than** | `\/dataentities\/Newsletter\/scroll?_where=date<2001-01-01` |\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Scrolldocuments", "parameters": [ { @@ -515,7 +509,10 @@ "$ref": "#/components/parameters/_sort" }, { - "$ref": "#/components/parameters/openData" + "$ref": "#/components/parameters/unmasked" + }, + { + "$ref": "#/components/parameters/reason" } ], "responses": { @@ -1307,7 +1304,8 @@ "PersonalDataRequest": { "title": "PersonalDataRequest", "required": [ - "fields" + "fields", + "data_subject_field" ], "type": "object", "description": "Configuration of personal data fields for a data entity.", @@ -1321,7 +1319,7 @@ }, "data_subject_field": { "type": "string", - "description": "Name of the field that identifies the data subject (owner of the personal data). Used for compliance with data subject requests such as the right to be forgotten. Can be overridden per document by the `dataSubject` query parameter on write endpoints." + "description": "Name of the field whose value identifies the data subject (owner of the personal data) in each document. Required for compliance with data subject requests such as the right to be forgotten. Every document saved in this entity must contain this field." } } }, @@ -1853,26 +1851,26 @@ "default": 100 } }, - "dataSubject": { - "name": "dataSubject", + "unmasked": { + "name": "unmasked", "in": "query", - "description": "Identifier of the owner (data subject) of the personal data in this document, used for compliance with data subject requests (e.g., right to be forgotten). If this parameter is present, it overrides any `data_subject_field` configured via the [Configure personal data fields](https://developers.vtex.com/docs/api-reference/master-data-api-v2#post-/api/dataentities/-dataEntityName-/personalData) endpoint. Only required when the data entity has personal data fields configured.", + "description": "When set to `true`, fields configured as personal data are returned with their original values instead of masked. Requires the `reason` query parameter. By default (`false`), personal data fields are returned with masked values (e.g., `j***@****.com`).", "required": false, "style": "form", "schema": { - "type": "string", - "example": "john@example.com" + "type": "boolean", + "default": false } }, - "openData": { - "name": "openData", + "reason": { + "name": "reason", "in": "query", - "description": "When set to `true`, fields configured as personal data are returned with their original values. By default (`false`), personal data fields are returned with masked values (e.g., `j***@****.com`).", + "description": "Description of the purpose for accessing unmasked personal data. Required when `unmasked=true`. This value is recorded for auditing purposes.", "required": false, "style": "form", "schema": { - "type": "boolean", - "default": false + "type": "string", + "example": "customer support request" } } } From d95c87facb7f6bf8a2197365327f1d236c9b7a94 Mon Sep 17 00:00:00 2001 From: Pedro Antunes <47991446+PedroAntunesCosta@users.noreply.github.com> Date: Fri, 24 Apr 2026 18:19:09 -0300 Subject: [PATCH 5/8] Spectral fixes --- VTEX - Master Data API - v2.json | 52 ++++++++++++-------------------- 1 file changed, 19 insertions(+), 33 deletions(-) diff --git a/VTEX - Master Data API - v2.json b/VTEX - Master Data API - v2.json index 793304559..36b9ff2a4 100644 --- a/VTEX - Master Data API - v2.json +++ b/VTEX - Master Data API - v2.json @@ -400,8 +400,7 @@ "REST-Content-Range": { "schema": { "type": "string", - "description": "Indicates the range of documents returned in the current response, as well as the total number of documents available in the dataset. The value follows the format `resources={x}-{y}/{total}`, where:\n* `x`: Index of the first document in the returned array.\n* `y`: Index of the last document in the returned array + 1.\n* `total`: Total number of documents that match the query.\nFor example, `resources=0-10/98` indicates that documents from 0 to 9 are returned out of a total of 98 matching documents.", - "example": "resources=0-10/98" + "description": "Indicates the range of documents returned in the current response, as well as the total number of documents available in the dataset. The value follows the format `resources={x}-{y}/{total}`, where:\n* `x`: Index of the first document in the returned array.\n* `y`: Index of the last document in the returned array + 1.\n* `total`: Total number of documents that match the query.\nFor example, `resources=0-10/98` indicates that documents from 0 to 9 are returned out of a total of 98 matching documents." } } }, @@ -466,7 +465,7 @@ } }, "503": { - "description": "Service Unavailable\n\nWildcard queries temporarily blocked due to excessive usage. Consider adjusting your code to remove them or reduce the rate of search requests with wildcards (*). This temporary block may also be due to excessive use of requests with the parameter `keyword`." + "description": "Service Unavailable\n\nWildcard queries temporarily blocked due to excessive usage." } }, "deprecated": false @@ -573,7 +572,7 @@ } }, "429": { - "description": "Too Many Requests\n\nWildcard queries temporarily blocked due to excessive usage. Consider adjusting your code to remove them or reduce the rate of search requests with wildcards (*). This temporary block may also be due to excessive use of requests with the parameter `keyword`." + "description": "Too Many Requests\n\nWildcard queries temporarily blocked due to excessive usage." } }, "deprecated": false @@ -582,7 +581,7 @@ "/api/dataentities/{dataEntityName}/personalData": { "post": { "tags": [ - "Personal Data" + "Personal data" ], "summary": "Configure personal data fields", "description": "Defines which fields of a data entity contain personal data. Fields configured as personal data are stored separately with encryption and special data residency, and are returned masked by default when retrieving documents. You can optionally indicate which field identifies the data subject (owner of the data), used for compliance with data subject requests such as the right to be forgotten.\r\n\r\n>ℹ️ Personal data configuration is set at the data entity level, not within individual schemas. This avoids conflicts when multiple schemas coexist for the same data entity.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", @@ -737,33 +736,18 @@ "schema": { "$ref": "#/components/schemas/SaveschemabynameRequest" }, - "examples": { - "minimal": { - "summary": "Minimal schema", - "value": { - "properties": { - "name": { - "type": "string" - } - } + "example": { + "properties": { + "skuId": { + "type": "string" + }, + "postalCode": { + "type": "string" } }, - "withVIndexed": { - "summary": "Schema with v-indexed for filter and sort", - "value": { - "properties": { - "skuId": { - "type": "string" - }, - "postalCode": { - "type": "string" - } - }, - "v-indexed": [ - "postalCode" - ] - } - } + "v-indexed": [ + "postalCode" + ] } } }, @@ -1313,7 +1297,8 @@ "fields": { "type": "array", "items": { - "type": "string" + "type": "string", + "description": "Name of a field that contains personal data." }, "description": "Names of fields that contain personal data. These fields are stored with encryption and special data residency, and are returned masked by default when retrieving documents." }, @@ -1396,7 +1381,8 @@ "v-indexed": { "type": "array", "items": { - "type": "string" + "type": "string", + "description": "Name of a property to index for /search, /scroll, and _sort." }, "description": "Names of properties to index for /search, /scroll, and _sort. Required for reliable filtering (e.g. _where=field=value) and sorting (_sort=field ASC). Indexing is asynchronous after schema save." } @@ -1886,7 +1872,7 @@ "name": "Scroll" }, { - "name": "Personal Data" + "name": "Personal data" }, { "name": "Schemas" From 6fc92f2da2bb3994533688efa9a13f2ba76bfcc4 Mon Sep 17 00:00:00 2001 From: Pedro Antunes <47991446+PedroAntunesCosta@users.noreply.github.com> Date: Wed, 29 Apr 2026 17:11:34 -0300 Subject: [PATCH 6/8] fix: align personal data API with implementation contract Rename unmasked query param to _unmasked to match the leading-underscore convention of other reserved params, drop the reason param, switch the configuration endpoint to PUT with PascalCase Fields/SubjectIdField body, add a GET endpoint to retrieve the current configuration, and document the 12h reprocessing lock with a 423 response. --- VTEX - Master Data API - v2.json | 108 ++++++++++++++++++++----------- 1 file changed, 70 insertions(+), 38 deletions(-) diff --git a/VTEX - Master Data API - v2.json b/VTEX - Master Data API - v2.json index 36b9ff2a4..6fca42b47 100644 --- a/VTEX - Master Data API - v2.json +++ b/VTEX - Master Data API - v2.json @@ -2,7 +2,7 @@ "openapi": "3.0.0", "info": { "title": "Master Data API - v2", - "description": ">ℹ️ Master Data v2 is not compatible with data entities from previous versions, such as CL and AD.\r\n\r\n[Master Data](https://developers.vtex.com/docs/guides/master-data-introduction) is a secure, fast, scalable, and extensible solution that allows users to create their own entities, store data, and retrieve information directly from the storefront or external integrations.\r\n\r\nSeveral internal VTEX modules use Master Data as a data repository, including Orders and Sales App. \r\n\r\nThere are two main ways to use Master Data:\r\n\r\n- [Directly from the storefront](#directly-from-the-storefront)\r\n- [With an external integration](#external-integrations)\r\n\r\n## Directly from the storefront\r\n\r\nWhen using Master Data within the storefront, consider the following:\r\n\r\n- Use the storefront host to query or store information to avoid issues related to Cross-origin resource sharing (CORS).\r\n- Use the relative path to avoid CORS issues.\r\n- Configure the JSON Schema of the Data Entity to specify which information should be public and which should not be.\r\n- Avoid creating query loops to prevent potential throttling issues or APIs being disabled due to security protection measures.\r\n- Never add authentication keys, such as `X-VTEX-API-AppKey` or `X-VTEX-API-AppToken`, via JavaScript as this could pose security risks.\r\n\r\n## External integrations\r\n\r\nWhen using Master Data to store data from an external integration, such as client data from another service, consider the following:\r\n\r\n- Use the host `{{accountName}}.vtexcommercestable.com.br`.\r\n- Use the authentication keys (`X-VTEX-API-AppKey` ou `X-VTEX-API-AppToken`).\r\n\r\n## Common parameters\r\n\r\n| Name | Description |\r\n| -------- | -------- |\r\n| `accountName` | Account name in VTEX License Manager. |\r\n| `name` | Data Entity name. |\r\n| `schema` | JSON Schema of a Data Entity. |\r\n| `id` | Identifier of a document. |\r\n| `X-VTEX-API-AppKey` | appKey. |\r\n| `X-VTEX-API-AppToken` | appToken. | \r\n\r\n## Index\r\n\r\n### Documents\r\n\r\n- `POST` [Create new document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#post-/api/dataentities/-dataEntityName-/documents)\r\n- `PATCH` [Create partial document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#patch-/api/dataentities/-dataEntityName-/documents)\r\n- `GET` [Get document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/documents/-id-)\r\n- `PUT` [Create document with custom ID or Update entire document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#put-/api/dataentities/-dataEntityName-/documents/-id-)\r\n- `PATCH` [Update partial document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#patch-/api/dataentities/-dataEntityName-/documents/-id-)\r\n- `DELETE` [Delete document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#delete-/api/dataentities/-dataEntityName-/documents/-id-)\r\n\r\n### Search\r\n\r\n- `GET` [Search documents](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/search)\r\n\r\n### Scroll\r\n\r\n- `GET` [Scroll documents](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/scroll)\r\n\r\n### Personal Data\r\n\r\n- `POST` [Configure personal data fields](https://developers.vtex.com/docs/api-reference/master-data-api-v2#post-/api/dataentities/-dataEntityName-/personalData)\r\n\r\n### Schemas\r\n\r\n- `GET` [Get schemas](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/schemas)\r\n- `GET` [Get schema by name](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/schemas/-schemaName-)\r\n- `PUT` [Save schema by name](https://developers.vtex.com/docs/api-reference/master-data-api-v2#put-/api/dataentities/-dataEntityName-/schemas/-schemaName-)\r\n- `DELETE` [Delete schema by name](https://developers.vtex.com/docs/api-reference/master-data-api-v2#delete-/api/dataentities/-dataEntityName-/schemas/-schemaName-)\r\n\r\n### Indices\r\n\r\n- `GET` [Get indices](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/indices)\r\n- `PUT` [Put indices](https://developers.vtex.com/docs/api-reference/master-data-api-v2#put-/api/dataentities/-dataEntityName-/indices)\r\n- `GET` [Get index by name](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/indices/-index_name-)\r\n- `DELETE` [Delete index by name](https://developers.vtex.com/docs/api-reference/master-data-api-v2#delete-/api/dataentities/-dataEntityName-/indices/-index_name-)\r\n\r\n### Clusters\r\n\r\n- `POST` [Validate document by clusters](https://developers.vtex.com/docs/api-reference/master-data-api-v2#post-/api/dataentities/-dataEntityName-/documents/-id-/clusters)\r\n\r\n### Versions\r\n\r\n- `GET` [List versions](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/documents/-id-/versions)\r\n- `GET` [Get version](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/documents/-id-/versions/-versionId-)\r\n- `PUT` [Put version](https://developers.vtex.com/docs/api-reference/master-data-api-v2#put-/api/dataentities/-dataEntityName-/documents/-id-/versions/-versionId-)", + "description": ">ℹ️ Master Data v2 is not compatible with data entities from previous versions, such as CL and AD.\r\n\r\n[Master Data](https://developers.vtex.com/docs/guides/master-data-introduction) is a secure, fast, scalable, and extensible solution that allows users to create their own entities, store data, and retrieve information directly from the storefront or external integrations.\r\n\r\nSeveral internal VTEX modules use Master Data as a data repository, including Orders and Sales App. \r\n\r\nThere are two main ways to use Master Data:\r\n\r\n- [Directly from the storefront](#directly-from-the-storefront)\r\n- [With an external integration](#external-integrations)\r\n\r\n## Directly from the storefront\r\n\r\nWhen using Master Data within the storefront, consider the following:\r\n\r\n- Use the storefront host to query or store information to avoid issues related to Cross-origin resource sharing (CORS).\r\n- Use the relative path to avoid CORS issues.\r\n- Configure the JSON Schema of the Data Entity to specify which information should be public and which should not be.\r\n- Avoid creating query loops to prevent potential throttling issues or APIs being disabled due to security protection measures.\r\n- Never add authentication keys, such as `X-VTEX-API-AppKey` or `X-VTEX-API-AppToken`, via JavaScript as this could pose security risks.\r\n\r\n## External integrations\r\n\r\nWhen using Master Data to store data from an external integration, such as client data from another service, consider the following:\r\n\r\n- Use the host `{{accountName}}.vtexcommercestable.com.br`.\r\n- Use the authentication keys (`X-VTEX-API-AppKey` ou `X-VTEX-API-AppToken`).\r\n\r\n## Common parameters\r\n\r\n| Name | Description |\r\n| -------- | -------- |\r\n| `accountName` | Account name in VTEX License Manager. |\r\n| `name` | Data Entity name. |\r\n| `schema` | JSON Schema of a Data Entity. |\r\n| `id` | Identifier of a document. |\r\n| `X-VTEX-API-AppKey` | appKey. |\r\n| `X-VTEX-API-AppToken` | appToken. | \r\n\r\n## Index\r\n\r\n### Documents\r\n\r\n- `POST` [Create new document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#post-/api/dataentities/-dataEntityName-/documents)\r\n- `PATCH` [Create partial document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#patch-/api/dataentities/-dataEntityName-/documents)\r\n- `GET` [Get document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/documents/-id-)\r\n- `PUT` [Create document with custom ID or Update entire document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#put-/api/dataentities/-dataEntityName-/documents/-id-)\r\n- `PATCH` [Update partial document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#patch-/api/dataentities/-dataEntityName-/documents/-id-)\r\n- `DELETE` [Delete document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#delete-/api/dataentities/-dataEntityName-/documents/-id-)\r\n\r\n### Search\r\n\r\n- `GET` [Search documents](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/search)\r\n\r\n### Scroll\r\n\r\n- `GET` [Scroll documents](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/scroll)\r\n\r\n### Personal Data\r\n\r\n- `GET` [Get personal data configuration](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/personalData)\r\n- `PUT` [Configure personal data fields](https://developers.vtex.com/docs/api-reference/master-data-api-v2#put-/api/dataentities/-dataEntityName-/personalData)\r\n\r\n### Schemas\r\n\r\n- `GET` [Get schemas](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/schemas)\r\n- `GET` [Get schema by name](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/schemas/-schemaName-)\r\n- `PUT` [Save schema by name](https://developers.vtex.com/docs/api-reference/master-data-api-v2#put-/api/dataentities/-dataEntityName-/schemas/-schemaName-)\r\n- `DELETE` [Delete schema by name](https://developers.vtex.com/docs/api-reference/master-data-api-v2#delete-/api/dataentities/-dataEntityName-/schemas/-schemaName-)\r\n\r\n### Indices\r\n\r\n- `GET` [Get indices](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/indices)\r\n- `PUT` [Put indices](https://developers.vtex.com/docs/api-reference/master-data-api-v2#put-/api/dataentities/-dataEntityName-/indices)\r\n- `GET` [Get index by name](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/indices/-index_name-)\r\n- `DELETE` [Delete index by name](https://developers.vtex.com/docs/api-reference/master-data-api-v2#delete-/api/dataentities/-dataEntityName-/indices/-index_name-)\r\n\r\n### Clusters\r\n\r\n- `POST` [Validate document by clusters](https://developers.vtex.com/docs/api-reference/master-data-api-v2#post-/api/dataentities/-dataEntityName-/documents/-id-/clusters)\r\n\r\n### Versions\r\n\r\n- `GET` [List versions](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/documents/-id-/versions)\r\n- `GET` [Get version](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/documents/-id-/versions/-versionId-)\r\n- `PUT` [Put version](https://developers.vtex.com/docs/api-reference/master-data-api-v2#put-/api/dataentities/-dataEntityName-/documents/-id-/versions/-versionId-)", "contact": {}, "version": "1.0" }, @@ -165,7 +165,7 @@ "Documents" ], "summary": "Get document", - "description": "Retrieves a document by ID.\n\r\n\r>ℹ️ Assign the `_fields` parameter in the query string to retrieve the desired fields. If you want to return all the fields use `_fields=_all`.\r\n\r\n>ℹ️ Fields [configured as personal data](https://developers.vtex.com/docs/api-reference/master-data-api-v2#post-/api/dataentities/-dataEntityName-/personalData) are returned with masked values by default. To retrieve the original values, add the `unmasked=true` query parameter (a `reason` is also required).\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", + "description": "Retrieves a document by ID.\n\r\n\r>ℹ️ Assign the `_fields` parameter in the query string to retrieve the desired fields. If you want to return all the fields use `_fields=_all`.\r\n\r\n>ℹ️ Fields [configured as personal data](https://developers.vtex.com/docs/api-reference/master-data-api-v2#put-/api/dataentities/-dataEntityName-/personalData) are returned with masked values by default. To retrieve the original values, add the `_unmasked=true` query parameter.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Getdocument", "parameters": [ { @@ -187,10 +187,7 @@ "$ref": "#/components/parameters/_schema" }, { - "$ref": "#/components/parameters/unmasked" - }, - { - "$ref": "#/components/parameters/reason" + "$ref": "#/components/parameters/_unmasked" } ], "responses": { @@ -359,7 +356,7 @@ "Search" ], "summary": "Search documents", - "description": "Retrieves Master Data v2 documents' information, while choosing which fields will be returned and filtering documents by specific fields.\r\n\r\n> The response header `REST-Content-Range` indicates the total amount of results for that specific search. For example, it may return `resources 0-100/136108`, which indicates it has returned the first 100 results out of a total of 136108.\r\n\r\nBelow you can see some query examples and learn more about each query parameter.\n\r\n\rLearn more about [Pagination in the Master Data API](https://developers.vtex.com/docs/guides/pagination-in-the-master-data-api).\r\n\r\n>ℹ️ Fields [configured as personal data](https://developers.vtex.com/docs/api-reference/master-data-api-v2#post-/api/dataentities/-dataEntityName-/personalData) are returned with masked values by default. To retrieve the original values, add the `unmasked=true` query parameter (a `reason` is also required). Personal data fields only support exact matching when used as search filters.\r\n\r\n>⚠️ Avoid sending too many requests with wildcards (`*`) in the search parameters or that use the `keyword` parameter. This may lead to this endpoint being temporarily blocked for your account. If this happens you will receive an error with status code `503`.\r\n\r\n## Query examples\r\n\r\n| **Query Type** | **Example** |\r\n|-|-|\r\n| **Simple filter** | `\/dataentities\/Newsletter\/search?email=my@email.com` |\r\n| **Complex filter** | `\/dataentities\/Newsletter\/search?_where=(firstName=Jon OR lastName=Smith) OR (createdIn between 2001-01-01 AND 2016-01-01)` |\r\n| **Date range** | `\/dataentities\/Newsletter\/search?_where=createdIn between 2001-01-01 AND 2016-01-01` |\r\n| **Range numeric fields** | `\/dataentities\/Newsletter\/search?_where=age between 18 AND 25` |\r\n| **Partial filter** | `\/dataentities\/Newsletter\/search?firstName=*Maria*` |\r\n| **Filter for null values** | `\/dataentities\/Newsletter\/search?_where=firstName is null` |\r\n| **Filter for non-null values** | `\/dataentities\/Newsletter\/search?_where=firstName is not null` |\r\n| **Filter for difference** | `\/dataentities\/Newsletter\/search?_where=firstName<>maria` |\r\n| **Filter greater than** | `\/dataentities\/Newsletter\/search?_where=number>5` |\r\n| **Filter less than** | `\/dataentities\/Newsletter\/search?_where=date<2001-01-01` |\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", + "description": "Retrieves Master Data v2 documents' information, while choosing which fields will be returned and filtering documents by specific fields.\r\n\r\n> The response header `REST-Content-Range` indicates the total amount of results for that specific search. For example, it may return `resources 0-100/136108`, which indicates it has returned the first 100 results out of a total of 136108.\r\n\r\nBelow you can see some query examples and learn more about each query parameter.\n\r\n\rLearn more about [Pagination in the Master Data API](https://developers.vtex.com/docs/guides/pagination-in-the-master-data-api).\r\n\r\n>ℹ️ Fields [configured as personal data](https://developers.vtex.com/docs/api-reference/master-data-api-v2#put-/api/dataentities/-dataEntityName-/personalData) are returned with masked values by default. To retrieve the original values, add the `_unmasked=true` query parameter. Personal data fields only support exact matching when used as search filters.\r\n\r\n>⚠️ Avoid sending too many requests with wildcards (`*`) in the search parameters or that use the `keyword` parameter. This may lead to this endpoint being temporarily blocked for your account. If this happens you will receive an error with status code `503`.\r\n\r\n## Query examples\r\n\r\n| **Query Type** | **Example** |\r\n|-|-|\r\n| **Simple filter** | `\/dataentities\/Newsletter\/search?email=my@email.com` |\r\n| **Complex filter** | `\/dataentities\/Newsletter\/search?_where=(firstName=Jon OR lastName=Smith) OR (createdIn between 2001-01-01 AND 2016-01-01)` |\r\n| **Date range** | `\/dataentities\/Newsletter\/search?_where=createdIn between 2001-01-01 AND 2016-01-01` |\r\n| **Range numeric fields** | `\/dataentities\/Newsletter\/search?_where=age between 18 AND 25` |\r\n| **Partial filter** | `\/dataentities\/Newsletter\/search?firstName=*Maria*` |\r\n| **Filter for null values** | `\/dataentities\/Newsletter\/search?_where=firstName is null` |\r\n| **Filter for non-null values** | `\/dataentities\/Newsletter\/search?_where=firstName is not null` |\r\n| **Filter for difference** | `\/dataentities\/Newsletter\/search?_where=firstName<>maria` |\r\n| **Filter greater than** | `\/dataentities\/Newsletter\/search?_where=number>5` |\r\n| **Filter less than** | `\/dataentities\/Newsletter\/search?_where=date<2001-01-01` |\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Searchdocuments", "parameters": [ { @@ -387,10 +384,7 @@ "$ref": "#/components/parameters/_sort" }, { - "$ref": "#/components/parameters/unmasked" - }, - { - "$ref": "#/components/parameters/reason" + "$ref": "#/components/parameters/_unmasked" } ], "responses": { @@ -477,7 +471,7 @@ "Scroll" ], "summary": "Scroll documents", - "description": "Returns a list of documents according to query parameter filters. If you need to query the entire database, or your collection is over 10000 documents, use this endpoint.\r\n\r\nIn the first request, the `X-VTEX-MD-TOKEN` token will be obtained in the response header. This token must be passed to the next request in the `_token` query string parameter. The token expires after 20 minutes of inactivity, and each request made with the token during this time resets the expiration timer.\r\n\r\nAfter the token is obtained, it is no longer necessary to send the filter or document size per page parameters. You only need to resend the token until the document collection is empty.\r\n\r\nFirst request:\r\n```\r\n/dataentities/Newsletter/scroll?isCluster=true&_size=250&_fields=email,firstName\r\n```\r\n\r\nRetrieve the token in the header `X-VTEX-MD-TOKEN` from the first request's response and use it to make the following requests.\r\n\r\nSubsequent requests:\r\n```\r\n/dataentities/Newsletter/scroll?_token={tokenValue}\r\n```\n\r\n\rLearn more about [Pagination in the Master Data API](https://developers.vtex.com/docs/guides/pagination-in-the-master-data-api).\r\n\r\n>ℹ️ Fields [configured as personal data](https://developers.vtex.com/docs/api-reference/master-data-api-v2#post-/api/dataentities/-dataEntityName-/personalData) are returned with masked values by default. To retrieve the original values, add the `unmasked=true` query parameter (a `reason` is also required).\r\n\r\n>⚠️ Avoid sending too many requests with wildcards (`*`) in the search parameters or using the `keyword` parameter. This may lead to this endpoint being temporarily blocked for your account. If this happens you will receive an error with status code `429`.\r\n\r\n## Query examples\r\n\r\n| **Query Type** | **Example** |\r\n|-|-|\r\n| **Simple filter** | `\/dataentities\/Newsletter\/scroll?email=my@email.com` |\r\n| **Complex filter** | `\/dataentities\/Newsletter\/scroll?_where=(firstName=Jon OR lastName=Smith) OR (createdIn between 2001-01-01 AND 2016-01-01)` |\r\n| **Date range** | `\/dataentities\/Newsletter\/scroll?_where=createdIn between 2001-01-01 AND 2016-01-01` |\r\n| **Range numeric fields** | `\/dataentities\/Newsletter\/scroll?_where=age between 18 AND 25` |\r\n| **Partial filter** | `\/dataentities\/Newsletter\/scroll?firstName=*Maria*` |\r\n| **Filter for null values** | `\/dataentities\/Newsletter\/scroll?_where=firstName is null` |\r\n| **Filter for non-null values** | `\/dataentities\/Newsletter\/scroll?_where=firstName is not null` |\r\n| **Filter for difference** | `\/dataentities\/Newsletter\/scroll?_where=firstName<>maria` |\r\n| **Filter greater than** | `\/dataentities\/Newsletter\/scroll?_where=number>5` |\r\n| **Filter less than** | `\/dataentities\/Newsletter\/scroll?_where=date<2001-01-01` |\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", + "description": "Returns a list of documents according to query parameter filters. If you need to query the entire database, or your collection is over 10000 documents, use this endpoint.\r\n\r\nIn the first request, the `X-VTEX-MD-TOKEN` token will be obtained in the response header. This token must be passed to the next request in the `_token` query string parameter. The token expires after 20 minutes of inactivity, and each request made with the token during this time resets the expiration timer.\r\n\r\nAfter the token is obtained, it is no longer necessary to send the filter or document size per page parameters. You only need to resend the token until the document collection is empty.\r\n\r\nFirst request:\r\n```\r\n/dataentities/Newsletter/scroll?isCluster=true&_size=250&_fields=email,firstName\r\n```\r\n\r\nRetrieve the token in the header `X-VTEX-MD-TOKEN` from the first request's response and use it to make the following requests.\r\n\r\nSubsequent requests:\r\n```\r\n/dataentities/Newsletter/scroll?_token={tokenValue}\r\n```\n\r\n\rLearn more about [Pagination in the Master Data API](https://developers.vtex.com/docs/guides/pagination-in-the-master-data-api).\r\n\r\n>ℹ️ Fields [configured as personal data](https://developers.vtex.com/docs/api-reference/master-data-api-v2#put-/api/dataentities/-dataEntityName-/personalData) are returned with masked values by default. To retrieve the original values, add the `_unmasked=true` query parameter.\r\n\r\n>⚠️ Avoid sending too many requests with wildcards (`*`) in the search parameters or using the `keyword` parameter. This may lead to this endpoint being temporarily blocked for your account. If this happens you will receive an error with status code `429`.\r\n\r\n## Query examples\r\n\r\n| **Query Type** | **Example** |\r\n|-|-|\r\n| **Simple filter** | `\/dataentities\/Newsletter\/scroll?email=my@email.com` |\r\n| **Complex filter** | `\/dataentities\/Newsletter\/scroll?_where=(firstName=Jon OR lastName=Smith) OR (createdIn between 2001-01-01 AND 2016-01-01)` |\r\n| **Date range** | `\/dataentities\/Newsletter\/scroll?_where=createdIn between 2001-01-01 AND 2016-01-01` |\r\n| **Range numeric fields** | `\/dataentities\/Newsletter\/scroll?_where=age between 18 AND 25` |\r\n| **Partial filter** | `\/dataentities\/Newsletter\/scroll?firstName=*Maria*` |\r\n| **Filter for null values** | `\/dataentities\/Newsletter\/scroll?_where=firstName is null` |\r\n| **Filter for non-null values** | `\/dataentities\/Newsletter\/scroll?_where=firstName is not null` |\r\n| **Filter for difference** | `\/dataentities\/Newsletter\/scroll?_where=firstName<>maria` |\r\n| **Filter greater than** | `\/dataentities\/Newsletter\/scroll?_where=number>5` |\r\n| **Filter less than** | `\/dataentities\/Newsletter\/scroll?_where=date<2001-01-01` |\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Scrolldocuments", "parameters": [ { @@ -508,10 +502,7 @@ "$ref": "#/components/parameters/_sort" }, { - "$ref": "#/components/parameters/unmasked" - }, - { - "$ref": "#/components/parameters/reason" + "$ref": "#/components/parameters/_unmasked" } ], "responses": { @@ -579,12 +570,57 @@ } }, "/api/dataentities/{dataEntityName}/personalData": { - "post": { + "get": { + "tags": [ + "Personal data" + ], + "summary": "Get personal data configuration", + "description": "Retrieves the personal data configuration for a data entity, including the list of fields flagged as personal data and the field used to identify the data subject.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", + "operationId": "GetPersonalDataConfiguration", + "parameters": [ + { + "$ref": "#/components/parameters/Accept" + }, + { + "$ref": "#/components/parameters/dataEntityName" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PersonalDataRequest" + }, + "example": { + "Fields": [ + "name", + "lastName", + "document", + "phone", + "email" + ], + "SubjectIdField": "email" + } + } + } + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found\n\nThe data entity does not have personal data configuration." + } + }, + "deprecated": false + }, + "put": { "tags": [ "Personal data" ], "summary": "Configure personal data fields", - "description": "Defines which fields of a data entity contain personal data. Fields configured as personal data are stored separately with encryption and special data residency, and are returned masked by default when retrieving documents. You can optionally indicate which field identifies the data subject (owner of the data), used for compliance with data subject requests such as the right to be forgotten.\r\n\r\n>ℹ️ Personal data configuration is set at the data entity level, not within individual schemas. This avoids conflicts when multiple schemas coexist for the same data entity.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", + "description": "Defines which fields of a data entity contain personal data and which field identifies the data subject (owner of the data). Fields configured as personal data are stored separately with encryption and special data residency, are returned masked by default when retrieving documents, and participate in data subject requests such as the right to be forgotten.\r\n\r\n>ℹ️ Personal data configuration is set at the data entity level, not within individual schemas. This avoids conflicts when multiple schemas coexist for the same data entity.\r\n\r\n>⚠️ Saving a new configuration triggers a background process that re-tokenizes all existing documents in the entity. While this process runs, this endpoint is locked for the affected entity for up to 12 hours to prevent concurrent reprocessing jobs.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "ConfigurePersonalDataFields", "parameters": [ { @@ -604,10 +640,14 @@ "$ref": "#/components/schemas/PersonalDataRequest" }, "example": { - "fields": [ + "Fields": [ + "name", + "lastName", + "document", + "phone", "email" ], - "data_subject_field": "email" + "SubjectIdField": "email" } } }, @@ -622,6 +662,9 @@ }, "403": { "description": "Forbidden" + }, + "423": { + "description": "Locked\n\nA previous configuration change is still being processed." } }, "deprecated": false @@ -1288,13 +1331,13 @@ "PersonalDataRequest": { "title": "PersonalDataRequest", "required": [ - "fields", - "data_subject_field" + "Fields", + "SubjectIdField" ], "type": "object", "description": "Configuration of personal data fields for a data entity.", "properties": { - "fields": { + "Fields": { "type": "array", "items": { "type": "string", @@ -1302,7 +1345,7 @@ }, "description": "Names of fields that contain personal data. These fields are stored with encryption and special data residency, and are returned masked by default when retrieving documents." }, - "data_subject_field": { + "SubjectIdField": { "type": "string", "description": "Name of the field whose value identifies the data subject (owner of the personal data) in each document. Required for compliance with data subject requests such as the right to be forgotten. Every document saved in this entity must contain this field." } @@ -1837,27 +1880,16 @@ "default": 100 } }, - "unmasked": { - "name": "unmasked", + "_unmasked": { + "name": "_unmasked", "in": "query", - "description": "When set to `true`, fields configured as personal data are returned with their original values instead of masked. Requires the `reason` query parameter. By default (`false`), personal data fields are returned with masked values (e.g., `j***@****.com`).", + "description": "When set to `true`, fields configured as personal data are returned with their original values instead of masked. Only takes effect if the data entity has personal data configured via [Configure personal data fields](https://developers.vtex.com/docs/api-reference/master-data-api-v2#put-/api/dataentities/-dataEntityName-/personalData); otherwise it is ignored. By default (`false`), personal data fields are returned with masked values (e.g., `j***@****.com`).", "required": false, "style": "form", "schema": { "type": "boolean", "default": false } - }, - "reason": { - "name": "reason", - "in": "query", - "description": "Description of the purpose for accessing unmasked personal data. Required when `unmasked=true`. This value is recorded for auditing purposes.", - "required": false, - "style": "form", - "schema": { - "type": "string", - "example": "customer support request" - } } } }, From 537f03b96e0f7688d6c47fb6f2ed6c1af9ddf5dc Mon Sep 17 00:00:00 2001 From: Pedro Antunes <47991446+PedroAntunesCosta@users.noreply.github.com> Date: Wed, 29 Apr 2026 22:20:01 -0300 Subject: [PATCH 7/8] fix: align personal data permissions with schemas endpoints Allow Read only documents, Insert or update document, and Full access to all documents resources on Get personal data configuration, matching Get schemas. Configure personal data fields already matches Save schema by name (Master Data administrator only). --- VTEX - Master Data API - v2.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/VTEX - Master Data API - v2.json b/VTEX - Master Data API - v2.json index 6fca42b47..84426ec56 100644 --- a/VTEX - Master Data API - v2.json +++ b/VTEX - Master Data API - v2.json @@ -575,7 +575,7 @@ "Personal data" ], "summary": "Get personal data configuration", - "description": "Retrieves the personal data configuration for a data entity, including the list of fields flagged as personal data and the field used to identify the data subject.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", + "description": "Retrieves the personal data configuration for a data entity, including the list of fields flagged as personal data and the field used to identify the data subject.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "GetPersonalDataConfiguration", "parameters": [ { From 5cb9fcd0f187c691ebd3c7b4a0d0cfb5ee7366d4 Mon Sep 17 00:00:00 2001 From: Pedro Antunes <47991446+PedroAntunesCosta@users.noreply.github.com> Date: Thu, 7 May 2026 12:38:10 -0300 Subject: [PATCH 8/8] Update VTEX - Master Data API - v2.json MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Isabella Veloso Sá <77300325+Isabella-Veloso@users.noreply.github.com> --- VTEX - Master Data API - v2.json | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/VTEX - Master Data API - v2.json b/VTEX - Master Data API - v2.json index 84426ec56..69dfb3dca 100644 --- a/VTEX - Master Data API - v2.json +++ b/VTEX - Master Data API - v2.json @@ -565,8 +565,7 @@ "429": { "description": "Too Many Requests\n\nWildcard queries temporarily blocked due to excessive usage." } - }, - "deprecated": false + } } }, "/api/dataentities/{dataEntityName}/personalData": {