Master Data API - v2

Create new document Creates a new document with an ID automatically generated by VTEX, corresponding to a new or existing data entity. If an unexisting `dataEntityName` is informed in the path, this endpoint will create the data entity as well as the new document. For example, you can create a new customer profile or address. >ℹ️ You can use this request to create documents for any data entity. Because of this, you are not restricted to using the fields exemplified below in your requests. However you should be aware of the fields allowed or required for each document you wish to create. > To create a document with a custom ID, refer to the [Create document with custom ID](https://developers.vtex.com/docs/api-reference/master-data-api-v2#put-/api/dataentities/-dataEntityName-/documents/-id-) endpoint. ## Permissions Any 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: | **Product** | **Category** | **Resource** | | --------------- | ----------------- | ----------------- | | Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** | | Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** | | Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** | There 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). >❗ 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.

Create partial document This request allows you to partially update a document corresponding to a given data entity. >ℹ️ You can use this request to create documents for any given data entity. Because of this, you are not restricted to using the fields exemplified below in your requests. But you should be aware of the fields allowed or required for each document you wish to update. ## Permissions Any 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: | **Product** | **Category** | **Resource** | | --------------- | ----------------- | ----------------- | | Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** | | Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** | | Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** | There 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). >❗ 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.

Delete document Deletes a document. ## Permissions Any 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: | **Product** | **Category** | **Resource** | | --------------- | ----------------- | ----------------- | | Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** | | Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** | There 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). >❗ 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.

Delete index by name Deletes an [index](https://developers.vtex.com/docs/guides/master-data-components#index). ## Permissions Any 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: | **Product** | **Category** | **Resource** | | --------------- | ----------------- | ----------------- | | Dynamic Storage | Index | **Remove index** | | Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** | There 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). >❗ 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.

Delete schema by name Deletes an existing [schema](https://developers.vtex.com/docs/guides/master-data-schema-lifecycle) for a given data entity. ## Permissions Any 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: | **Product** | **Category** | **Resource** | | --------------- | ----------------- | ----------------- | | Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** | There 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). >❗ 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.

Get document Retrieves a document by ID. >ℹ️ Assign the `_fields` parameter in the query string to retrieve the desired fields. If you want to return all the fields use `_fields=_all`. ## Permissions Any 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: | **Product** | **Category** | **Resource** | | --------------- | ----------------- | ----------------- | | Dynamic Storage | Dynamic storage generic resources | **Read only documents** | | Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** | | Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** | | Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** | There 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). >❗ 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.

Get index by name Retrieves an [index](https://developers.vtex.com/docs/guides/master-data-components#index). ## Permissions Any 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: | **Product** | **Category** | **Resource** | | --------------- | ----------------- | ----------------- | | Dynamic Storage | Index | **View index details** | | Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** | There 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). >❗ 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.

Get indices Returns the list of [indices](https://developers.vtex.com/docs/guides/master-data-components#index) by data entity. ## Permissions Any 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: | **Product** | **Category** | **Resource** | | --------------- | ----------------- | ----------------- | | Dynamic Storage | Index | **View index details** | | Dynamic Storage | Index | **List index** | | Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** | There 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). >❗ 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.

Get schema by name Returns an existing [schema](https://developers.vtex.com/docs/guides/master-data-schema-lifecycle) for a given data entity. ## Permissions Any 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: | **Product** | **Category** | **Resource** | | --------------- | ----------------- | ----------------- | | Dynamic Storage | Dynamic storage generic resources | **Read only documents** | | Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** | | Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** | | Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** | There 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). >❗ 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.

Get schemas Retrieves all existing [schemas](https://developers.vtex.com/docs/guides/master-data-schema-lifecycle) for a given data entity. ## Permissions Any 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: | **Product** | **Category** | **Resource** | | --------------- | ----------------- | ----------------- | | Dynamic Storage | Dynamic storage generic resources | **Read only documents** | | Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** | | Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** | | Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** | There 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). >❗ 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.

Get version Returns the version of a document. >ℹ Master Data documents are versioned. This means that, for each change, a new version is generated. ## Permissions Any 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: | **Product** | **Category** | **Resource** | | --------------- | ----------------- | ----------------- | | Dynamic Storage | Dynamic storage generic resources | **Read only documents** | | Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** | | Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** | | Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** | There 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). >❗ 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.

List versions Lists the versions of a document. >ℹ Master Data documents are versioned. This means that, for each change, a new version is generated. ## Permissions Any 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: | **Product** | **Category** | **Resource** | | --------------- | ----------------- | ----------------- | | Dynamic Storage | Dynamic storage generic resources | **Read only documents** | | Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** | | Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** | | Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** | There 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). >❗ 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.

Create index Creates an [index](https://developers.vtex.com/docs/guides/master-data-components#index). ## Permissions Any 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: | **Product** | **Category** | **Resource** | | --------------- | ----------------- | ----------------- | | Dynamic Storage | Index | **Edit index** | | Dynamic Storage | Index | **Create index** | | Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** | There 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). >❗ 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.

Update version Updates the document's version value. >ℹ Master Data documents are versioned. This means that, for each change, a new version is generated. ## Permissions Any 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: | **Product** | **Category** | **Resource** | | --------------- | ----------------- | ----------------- | | Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** | | Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** | | Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** | There 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). >❗ 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.

Save schema by name 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). > Note that if you send a `schemaName` that does not exist for that data entity, this request will create it. This 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). > Each Master Data v2 data entity can have up to 60 schemas. ## Indexing fields for search, scroll and sort To 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). - `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. - `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. **Example request body with `v-indexed`:** ```json { "properties": { "skuId": { "type": "string" }, "postalCode": { "type": "string" } }, "v-indexed": ["postalCode"] } ``` > ℹ️ 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. ## Reindex lock Saving a schema can trigger a full reindex of the data entity. The reindex lock works in two stages: 1. **Locking the data entity:** The lock starts only when a schema save triggers a reindex. Schema saves that don't trigger a reindex never lock the data entity. 2. **While the lock is active:** Every later schema save for that same data entity is rejected with `423 Locked`, including saves that would not trigger a reindex on their own. The response states that the reindex is still in progress. A schema save can trigger a new reindex of the same data entity only after an interval of 12 hours. Don't calculate a retry time from this interval. To know when the data entity accepts schema saves again, read the `Message` field of the `423 Locked` response, which states the time after which you can retry. When that time is not available, the message asks you to try again later. ## Permissions Any 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: | **Product** | **Category** | **Resource** | | --------------- | ----------------- | ----------------- | | Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** | There 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). >❗ 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.

Scroll documents 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. In 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. After 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. First request: ``` /dataentities/Newsletter/scroll?isCluster=true&_size=250&_fields=email,firstName ``` Retrieve the token in the header `X-VTEX-MD-TOKEN` from the first request's response and use it to make the following requests. Subsequent requests: ``` /dataentities/Newsletter/scroll?_token={tokenValue} ``` Learn more about [Pagination in the Master Data API](https://developers.vtex.com/docs/guides/pagination-in-the-master-data-api). >⚠️ 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`. ## Query examples | **Query Type** | **Example** | |-|-| | **Simple filter** | `/dataentities/Newsletter/[email protected]` | | **Complex filter** | `/dataentities/Newsletter/scroll?_where=(firstName=Jon OR lastName=Smith) OR (createdIn between 2001-01-01 AND 2016-01-01)` | | **Date range** | `/dataentities/Newsletter/scroll?_where=createdIn between 2001-01-01 AND 2016-01-01` | | **Range numeric fields** | `/dataentities/Newsletter/scroll?_where=age between 18 AND 25` | | **Partial filter** | `/dataentities/Newsletter/scroll?firstName=*Maria*` | | **Filter for null values** | `/dataentities/Newsletter/scroll?_where=firstName is null` | | **Filter for non-null values** | `/dataentities/Newsletter/scroll?_where=firstName is not null` | | **Filter for difference** | `/dataentities/Newsletter/scroll?_where=firstName<>maria` | | **Filter greater than** | `/dataentities/Newsletter/scroll?_where=number>5` | | **Filter less than** | `/dataentities/Newsletter/scroll?_where=date❗ 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.

Search documents Retrieves Master Data v2 documents' information, while choosing which fields will be returned and filtering documents by specific fields. > 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. Below you can see some query examples and learn more about each query parameter. Learn more about [Pagination in the Master Data API](https://developers.vtex.com/docs/guides/pagination-in-the-master-data-api). >⚠️ 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`. ## Query examples | **Query Type** | **Example** | |-|-| | **Simple filter** | `/dataentities/Newsletter/[email protected]` | | **Complex filter** | `/dataentities/Newsletter/search?_where=(firstName=Jon OR lastName=Smith) OR (createdIn between 2001-01-01 AND 2016-01-01)` | | **Date range** | `/dataentities/Newsletter/search?_where=createdIn between 2001-01-01 AND 2016-01-01` | | **Range numeric fields** | `/dataentities/Newsletter/search?_where=age between 18 AND 25` | | **Partial filter** | `/dataentities/Newsletter/search?firstName=*Maria*` | | **Filter for null values** | `/dataentities/Newsletter/search?_where=firstName is null` | | **Filter for non-null values** | `/dataentities/Newsletter/search?_where=firstName is not null` | | **Filter for difference** | `/dataentities/Newsletter/search?_where=firstName<>maria` | | **Filter greater than** | `/dataentities/Newsletter/search?_where=number>5` | | **Filter less than** | `/dataentities/Newsletter/search?_where=date❗ 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.

Create document with custom ID or update entire document Creates a new document with a custom ID, or updates an entire document if there is already a document with the informed ID. For example, you can update a customer profile or address. >ℹ️ You can use this request to create or update documents in any given data entity. Because of this, you are not restricted to using the fields exemplified below in your requests. But you should be aware of the fields allowed or required for each document you wish to update. A## Permissions Any 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: | **Product** | **Category** | **Resource** | | --------------- | ----------------- | ----------------- | | Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** | | Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** | | Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** | There 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). >❗ 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.

Update partial document This request allows you to partially update a document corresponding to a given data entity. For example, you can update some fields of a customer profile or address. >ℹ️ You can use this request to update documents for any given data entity. Because of this, you are not restricted to using the fields exemplified below in your requests. But you should be aware of the fields allowed or required for each document you wish to update. ## Permissions Any 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: | **Product** | **Category** | **Resource** | | --------------- | ----------------- | ----------------- | | Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** | | Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** | | Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** | There 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). >❗ 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.

Validate document by clusters Checks if a document is present in one or more clusters (specific set of field values). >ℹ️ There is a limit of five rules per request. ## Permissions Any 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: | **Product** | **Category** | **Resource** | | --------------- | ----------------- | ----------------- | | Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** | | Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** | | Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** | There 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). >❗ 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.

Get bulk document deletion job status Retrieves the current status of a bulk document deletion job created with the [Create bulk document deletion job](https://developers.vtex.com/docs/api-reference/master-data-api-v2#post-/api/dataentities/-dataEntityName-/delete) endpoint. Poll this endpoint until the job leaves the `InProgress` status. Possible `Status` values: - `InProgress`: The job is running and documents are being deleted in batches. Keep polling and do not create another job for this data entity. - `Success`: All matching documents were deleted. Compare `DocumentsDeleted` with the number of documents you expected to delete. - `Failed`: Processing stopped after exhausting internal retries. The deletion is partial, which means that documents from completed batches were already deleted. Fix the underlying cause and create a new job with the same filter to finish the deletion. ## Errors | Status code | Cause | What to do | | - | - | - | | `404` | The `jobId` does not exist for this account and data entity, or the job was created more than 60 days ago. Job records are kept for 60 days after creation. | Check the `jobId`, the `an` query parameter, and the data entity in the URL. If all three are correct, the job is older than 60 days and its record is no longer available. | ## Permissions This request requires a valid [user token](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens), sent in the `VtexIdclientAutCookie` header.

Create bulk document deletion job Creates an asynchronous job that deletes all documents in a data entity that match a given filter. This request does not delete any documents by itself. It creates a job and returns a `JobId`, which you must use to track the job with the [Get bulk document deletion job status](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/delete/jobs/-jobId-) endpoint. >❗ This action cannot be undone. Deleted documents will be permanently lost. ## Filter rules - The `filter` field is required. - Wildcards are not allowed. For example, `email = *@gmail.com` is rejected. - Every field used in the filter must be indexed. Internal fields, such as `createdIn`, are already indexed. - Filtering on a custom field also requires sending the `schema` that declares it as indexed in the request body. A custom field is declared as indexed for filtering in the `v-indexed` array of its [schema](https://developers.vtex.com/docs/api-reference/master-data-api-v2#put-/api/dataentities/-dataEntityName-/schemas/-schemaName-). - Only one active job per account and data entity is allowed at a time. >ℹ️ Confirm how many documents match your filter before deleting them, so you can compare that number with the `DocumentsDeleted` value returned by the job status endpoint. ## Errors `{field}`, `{schema}`, and `{entity}` are placeholders for values from your request, and any quotation marks around them are part of the message returned by the API. Messages marked as truncated continue beyond the text shown. | Status code | Message or cause | What to do | | - | - | - | | `400` | `The 'filter' field is required.` | Send the `filter` field in the body. | | `400` | `Wildcard filters are not allowed for bulk delete.` | Rewrite the filter using exact or range conditions over indexed fields. | | `400` | `The field '{field}' is not an internal indexed field, so the 'schema' that declares it as indexed must be provided.` | Send the `schema` field in the body. | | `400` | `The field '{field}' is not indexed in the schema '{schema}'...` (truncated) | Mark the field as indexed in the schema and wait for reindexing, or filter on an already indexed field. | | `400` | `Invalid data entity name.` | Correct the data entity name in the URL. Invalid characters are rejected. | | `400` | The request body is empty or is not valid JSON. This response uses the standard validation error format and does not include the `Message` field. | Send a valid JSON body. | | `409` | `Bulk deletion job creation failed for entity {entity}`, returned when a job is already `InProgress` for this account and data entity. | Track the existing job and resend once its status is `Success` or `Failed`. If a job appears stuck, the data entity automatically accepts new jobs after 12 hours. | | `415` | The `Content-Type: application/json` header is missing or the media type is not supported. | Send the `Content-Type: application/json` header. | | `5xx` | Transient infrastructure failure during job creation. | No residual state is left behind, so you can resend the request. | ## Permissions This request requires a valid [user token](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens), sent in the `VtexIdclientAutCookie` header.