The VTEX Master Data API is a NoSQL document store built into the VTEX platform. It provides schema-flexible data entity management with CRUD operations, full-text search, and indexing. Used for storing customer profiles, wishlists, subscriptions, and custom business data.
openapi: 3.0.0
info:
title: VTex 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-)"
contact: {}
version: '1.0'
servers:
- url: https://{accountName}.{environment}.com.br
description: VTEX server URL.
variables:
accountName:
description: Name of the VTEX account. Used as part of the URL
default: apiexamples
environment:
description: Environment to use. Used as part of the URL.
enum:
- vtexcommercestable
default: vtexcommercestable
paths:
/api/dataentities/{dataEntityName}/documents:
post:
tags:
- Documents
summary: VTex Create new document
description: "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.\r\n\r\n>ℹ️ 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.\r\n\r\n> 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.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-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 | **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 app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations."
operationId: Createnewdocument
parameters:
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/dataEntityName'
- $ref: '#/components/parameters/_schema'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentRequest'
example:
email: [email protected]
firstName: Clark
lastName: Kent
phone: '+12025550195'
documentType: CPF
document: '12345678900'
isCorporate: false
isNewsletterOptIn: false
localeDefault: en-US
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDocumentResponse'
example:
Id: Newsletter-cbfc4f67-6ea3-11ee-83ab-0a8d18f9f827
Href: http://cosmetics2.vtexcommercestable.com.br/api/dataentities/Newsletter/documents/cbfc4f67-6ea3-11ee-83ab-0a8d18f9f827
DocumentId: cbfc4f67-6ea3-11ee-83ab-0a8d18f9f827
deprecated: false
patch:
tags:
- Documents
summary: VTex Create partial document
description: "This request allows you to partially update a document corresponding to a given data entity.\r\n\r\n>ℹ️ 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.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-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 | **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 app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations."
operationId: Createorupdatepartialdocument
parameters:
- $ref: '#/components/parameters/dataEntityName'
- $ref: '#/components/parameters/_schema'
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/Accept'
requestBody:
description: JSON with the fields to be updated.
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentRequest'
example:
phone: '+12025550195'
isNewsletterOptIn: false
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/documentResponse'
example:
Id: Newsletter-b818cbda-e489-11e6-94f4-0ac138d2d42e
Href: http://api.vtex.com/apiexamples/dataentities/Newsletter/documents/b818cbda-e489-11e6-94f4-0ac138d2d42e
deprecated: false
/api/dataentities/{dataEntityName}/documents/{id}:
get:
tags:
- Documents
summary: VTex 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 [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-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 app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations."
operationId: Getdocument
parameters:
- $ref: '#/components/parameters/dataEntityName'
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/id'
- $ref: '#/components/parameters/_fields'
- $ref: '#/components/parameters/_schema'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Using_fields_all'
example:
id: b818cbda-e489-11e6-94f4-0ac138d2d42e
accountId: 14af940d-9300-4279-9355-61d44c2ff879
accountName: apiexamples
dataEntityId: Newsletter
deprecated: false
put:
tags:
- Documents
summary: VTex Create document with custom ID or Update entire document
description: "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.\r\n\r\n>ℹ️ 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.\r\n\r\nA## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-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 | **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 app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations."
operationId: Updateentiredocument
parameters:
- $ref: '#/components/parameters/dataEntityName'
- $ref: '#/components/parameters/_where'
- $ref: '#/components/parameters/_schema'
- $ref: '#/components/parameters/Accept'
- name: id
in: path
description: ID of the document. If you inform an **unused ID**, this endpoint will create a new document with the informed custom ID, differently from the [Create new document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#post-/api/dataentities/-dataEntityName-/documents) endpoint, which automatically generates the ID. If you inform an **existing ID**, this endpoint will update the entire document associated with the informed ID.
required: true
style: simple
schema:
type: string
example: Newsletter-b818cbda-e489-11e6-94f4-0ac138d2d42e
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentRequest'
example:
email: [email protected]
firstName: Clark
lastName: Kent
phone: '+12025550195'
documentType: CPF
document: '12345678900'
isCorporate: false
isNewsletterOptIn: false
localeDefault: en-US
required: true
responses:
'200':
description: OK. Document changed successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/documentResponse'
example:
Id: Newsletter-b818cbda-e489-11e6-94f4-0ac138d2d42e
Href: http://api.vtex.com/apiexamples/dataentities/Newsletter/documents/b818cbda-e489-11e6-94f4-0ac138d2d42e
'201':
description: Created. Document created successfully.
'304':
description: Not Modified. There were no changes to the document.
'400':
description: Bad Request. Invalid information in JSON.
'403':
description: Forbidden. Unauthorized access.
deprecated: false
patch:
tags:
- Documents
summary: VTex Update partial document
description: "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.\r\n\r\n>ℹ️ 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.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-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 | **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 app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations."
operationId: Updatepartialdocument
parameters:
- $ref: '#/components/parameters/dataEntityName'
- $ref: '#/components/parameters/_where'
- $ref: '#/components/parameters/_schema'
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/id'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentRequest'
example:
phone: '+12025550195'
isNewsletterOptIn: false
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/documentResponse'
example:
Id: Newsletter-b818cbda-e489-11e6-94f4-0ac138d2d42e
Href: http://api.vtex.com/apiexamples/dataentities/Newsletter/documents/b818cbda-e489-11e6-94f4-0ac138d2d42e
deprecated: false
delete:
tags:
- Documents
summary: VTex Delete document
description: "Deletes a document. \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-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 | **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 app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations."
operationId: Deletedocument
parameters:
- $ref: '#/components/parameters/dataEntityName'
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/id'
responses:
'200':
description: OK
headers: {}
deprecated: false
/api/dataentities/{dataEntityName}/search:
get:
tags:
- Search
summary: VTex Search documents
description: "Retrieves 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 results from 0 to 100 of a total 136108.\r\n\r\nBelow you can see some query examples and learn more about each query parameter.\n\r\n\r> 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### Simple filter\r\n\r\n```\r\n/dataentities/Newsletter/[email protected]\r\n```\r\n\r\n### Complex filter\r\n\r\n```\r\n/dataentities/Newsletter/search?_where=(firstName=Jon OR lastName=Smith) OR (createdIn between 2001-01-01 AND 2016-01-01)\r\n```\r\n\r\n### Date Range\r\n\r\n```\r\n/dataentities/Newsletter/search?_where=createdIn between 2001-01-01 AND 2016-01-01\r\n```\r\n\r\n### Range numeric fields\r\n\r\n```\r\n/dataentities/Newsletter/search?_where=age between 18 AND 25\r\n```\r\n\r\n### Partial filter\r\n\r\n```\r\n/dataentities/Newsletter/search?firstName=*Maria*\r\n```\r\n\r\n### Filter for null values\r\n\r\n```\r\n/dataentities/Newsletter/search?_where=firstName is null\r\n```\r\n\r\n### Filter for non-null values\r\n\r\n```\r\n/dataentities/Newsletter/search?_where=firstName is not null\r\n```\r\n\r\n### Filter for difference\r\n```\r\n/dataentities/Newsletter/search?_where=firstName<>maria\r\n```\r\n\r\n### Filter greater than or less than\r\n```\r\n/dataentities/Newsletter/search?_where=number>5\r\n/dataentities/Newsletter/search?_where=date<2001-01-01\r\n``` \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-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 app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations."
operationId: Searchdocuments
parameters:
- $ref: '#/components/parameters/dataEntityName'
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/REST-Range'
- $ref: '#/components/parameters/_fields'
- $ref: '#/components/parameters/_where'
- $ref: '#/components/parameters/_schema'
- $ref: '#/components/parameters/_sort'
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
description: List of documents that correspond to the result of the search.
items:
$ref: '#/components/schemas/Using_fields_all'
example:
- id: b818cbda-e489-11e6-94f4-0ac138d2d42e
accountId: 14af940d-9300-4279-9355-61d44c2ff879
accountName: apiexamples
dataEntityId: Newsletter
'400':
description: Bad Request
content:
application/json:
schema:
type: object
description: Response body object.
properties:
Message:
type: string
description: Error message.
example:
Message: Field 'X' not found in schema
'403':
description: Forbidden
content:
application/json:
schema:
type: object
description: Response body object.
properties:
Message:
type: string
description: Error message.
example:
Message: Cannot filter by private fields
'503':
description: Service Unavailable. Wildcard 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`.
deprecated: false
/api/dataentities/{dataEntityName}/scroll:
get:
tags:
- Scroll
summary: VTex Scroll documents
description: "If you need to query the entire VTEX Master Data database, or your collection is over 10.000 documents, use this endpoint.\r\n\r\nIn the first request, the `X-VTEX-MD-TOKEN` token will be returned in the header. This token must be passed to the next request in the query string `_token` parameter. The token has a timeout of 10 minutes, which refreshes after each request.\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. \n\r\n\r>⚠️ 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## Request examples\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``` \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-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 reques
# --- truncated at 32 KB (78 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/vtex/refs/heads/main/openapi/vtex-master-data-openapi-original.yml