{ "openapi": "3.0.0", "info": { "title": "Master Data API - v1", "description": "Master Data is a highly customizable VTEX database solution, which enables you to create applications. By default, Master Data is used to store and organize Customer data from your store. It features a powerful search engine, allowing you to store, search, expand, and customize data. Learn more about [Master Data v1](https://help.vtex.com/en/tutorial/master-data--4otjBnR27u4WUIciQsmkAw).\r\n\r\n>⚠️ Do not use Master Data as a log, cache, or temporary data store. Writing high volumes of disposable data can trigger API throttling and degrade store performance.", "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": { "get": { "tags": [ "Data entities" ], "summary": "List data entities", "description": "Retrieves the list of existing data entities in the store. \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| Dynamic Storage | Data entity | **List data entity** |\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": "Listdataentities", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Listdataentity" } }, "example": [ { "acronym": "SP", "name": "Sample", "primaryKeyType": "GUID", "allowGetAll": false }, { "acronym": "AD", "name": "Endereço", "primaryKeyType": "GUID", "allowGetAll": false }, { "acronym": "CL", "name": "Cliente", "primaryKeyType": "GUID", "allowGetAll": false } ] } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "Message": { "type": "string", "description": "Error message." } } }, "example": { "Message": "Unauthorized" } } } } } } }, "/api/dataentities/{acronym}": { "get": { "tags": [ "Data entities" ], "summary": "Get data entity structure", "description": "Returns the data entity structure with its respective fields and data type. \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| Dynamic Storage | Data entity | **View data entity details** |\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": "Getdataentitystructure", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "name": "acronym", "in": "path", "description": "Data entity acronym.", "required": true, "style": "simple", "schema": { "type": "string", "example": "SP" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Getdataentityfields" }, "example": { "acronym": "SP", "name": "Sample", "primaryKeyType": "GUID", "allowGetAll": false, "fields": [ { "name": "updatedIn", "type": "Date and Time", "displayName": "Atualizado em", "isNullable": true, "isSearchable": false, "isFilter": true, "isInternal": true }, { "name": "updatedBy", "type": "User Login", "displayName": "Atualizado por", "isNullable": true, "isSearchable": false, "isFilter": true, "isInternal": true }, { "name": "Auto_Increment", "type": "Auto Increment", "displayName": "Auto increment", "isNullable": true, "isSearchable": false, "isFilter": false, "isInternal": false }, { "name": "Boolean", "type": "Boolean", "displayName": "Boolean", "isNullable": true, "isSearchable": false, "isFilter": true, "isInternal": false }, { "name": "createdIn", "type": "Date and Time", "displayName": "Criado em", "isNullable": true, "isSearchable": false, "isFilter": true, "isInternal": true }, { "name": "createdBy", "type": "User Login", "displayName": "Criado por", "isNullable": true, "isSearchable": false, "isFilter": true, "isInternal": true }, { "name": "Currency", "type": "Currency", "displayName": "Currency", "isNullable": true, "isSearchable": false, "isFilter": true, "isInternal": false }, { "name": "Date", "type": "Date", "displayName": "Date", "isNullable": true, "isSearchable": false, "isFilter": true, "isInternal": false }, { "name": "Date_Time", "type": "Date and Time", "displayName": "Date and Time", "isNullable": true, "isSearchable": false, "isFilter": true, "isInternal": false }, { "name": "Decimal", "type": "Decimal", "displayName": "Decimal", "isNullable": true, "isSearchable": false, "isFilter": true, "isInternal": false }, { "name": "Email", "type": "Email", "displayName": "Email", "isNullable": true, "isSearchable": true, "isFilter": false, "isInternal": false }, { "name": "dataEntityId", "type": "Varchar 10", "displayName": "Entidade de dados", "isNullable": false, "isSearchable": true, "isFilter": false, "isInternal": true }, { "name": "File", "type": "File", "displayName": "File", "isNullable": true, "isSearchable": false, "isFilter": false, "isInternal": false }, { "name": "auto_filter", "type": "Text", "displayName": "Filtro automático", "isNullable": true, "isSearchable": false, "isFilter": false, "isInternal": true }, { "name": "accountId", "type": "Varchar 50", "displayName": "ID da loja", "isNullable": false, "isSearchable": false, "isFilter": false, "isInternal": true }, { "name": "id", "type": "Varchar 100", "displayName": "Id do documento", "isNullable": false, "isSearchable": true, "isFilter": false, "isInternal": true }, { "name": "Integer", "type": "Integer", "displayName": "Integer", "isNullable": true, "isSearchable": false, "isFilter": true, "isInternal": false }, { "name": "Long", "type": "Long", "displayName": "Long", "isNullable": true, "isSearchable": false, "isFilter": true, "isInternal": false }, { "name": "accountName", "type": "Varchar 100", "displayName": "Nome da loja", "isNullable": false, "isSearchable": true, "isFilter": false, "isInternal": true }, { "name": "Percent", "type": "Percent", "displayName": "Percent", "isNullable": true, "isSearchable": false, "isFilter": true, "isInternal": false }, { "name": "Relationship", "type": "Relationship", "displayName": "Relationship", "isNullable": true, "isSearchable": true, "isFilter": false, "isInternal": false }, { "name": "Score2", "type": "Score2", "displayName": "Score2", "isNullable": true, "isSearchable": false, "isFilter": true, "isInternal": false }, { "name": "followers", "type": "Text", "displayName": "Seguidores", "isNullable": true, "isSearchable": true, "isFilter": false, "isInternal": true }, { "name": "tags", "type": "Text", "displayName": "Tags", "isNullable": true, "isSearchable": true, "isFilter": false, "isInternal": true }, { "name": "Text", "type": "Text", "displayName": "Text", "isNullable": true, "isSearchable": false, "isFilter": false, "isInternal": false }, { "name": "Time", "type": "Time", "displayName": "Time", "isNullable": true, "isSearchable": false, "isFilter": false, "isInternal": false }, { "name": "lastInteractionIn", "type": "Date and Time", "displayName": "Ultima interação em", "isNullable": true, "isSearchable": false, "isFilter": true, "isInternal": true }, { "name": "lastInteractionBy", "type": "User Login", "displayName": "Ultima interação por", "isNullable": true, "isSearchable": false, "isFilter": true, "isInternal": true }, { "name": "URL", "type": "URL", "displayName": "URL", "isNullable": true, "isSearchable": false, "isFilter": true, "isInternal": false }, { "name": "User_Login", "type": "User Login", "displayName": "User Login", "isNullable": true, "isSearchable": true, "isFilter": false, "isInternal": false }, { "name": "Varchar10", "type": "Varchar 10", "displayName": "Varchar 10", "isNullable": true, "isSearchable": true, "isFilter": false, "isInternal": false }, { "name": "Varchar100", "type": "Varchar 100", "displayName": "Varchar 100", "isNullable": true, "isSearchable": true, "isFilter": false, "isInternal": false }, { "name": "Varchar50", "type": "Varchar 50", "displayName": "Varchar 50", "isNullable": true, "isSearchable": true, "isFilter": false, "isInternal": false }, { "name": "Varchar750", "type": "Varchar 750", "displayName": "Varchar 750", "isNullable": true, "isSearchable": true, "isFilter": false, "isInternal": false } ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "Message": { "type": "string", "description": "Error message." } } }, "example": { "Message": "Unauthorized" } } } } } } }, "/api/dataentities/{acronym}/documents": { "post": { "tags": [ "Documents" ], "summary": "Create new document", "description": "Creates a new document with an ID automatically generated by VTEX, corresponding to a given data entity. The request body is a JSON object where the key is the name of the field.\r\n\r\n>⚠️ Do not use Master Data as a log, cache, or temporary data store. Writing high volumes of disposable data can trigger API throttling and degrade store performance.\r\n\r\n>ℹ️ You can use this request to create 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\n## Custom field types\r\n\r\nThe table below presents the types of custom fields you can use when creating or updating documents in Master Data v1 and example values.\r\n\r\n| Field Type| Example value |\r\n| - | - |\r\n| Boolean | `true` |\r\n| Currency | `2.5` |\r\n| Date | `1992-11-17` |\r\n| Date_Time | `2016-09-14T19:21:01.3163733Z` |\r\n| Decimal | `2.5` |\r\n| Email | `meu@email.com` |\r\n| Integer | `1000000` |\r\n| Long | `1000000000` |\r\n| Percent | `85.42` |\r\n| Time | `23:50` |\r\n| URL | `https://www.vtex.com` |\r\n| Varchar10 | `Lorem ipsu` |\r\n| Varchar50 | `Lorem ipsum dolor sit amet, consectetur adipiscing` |\r\n| Varchar750 | `Lorem ipsum dolor sit amet, consectetur adipiscing elit...` |\r\n| Varchar100 | `Lorem ipsum dolor sit amet, consectetur adipiscing elit...` |\r\n| Relationship | `5eb31afb-7ab0-11e6-94b4-0a44686e393f` |\r\n| Text | `Lorem ipsum dolor sit amet, consectetur adipiscing elit...` |\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 | **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": "Createnewdocument", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/acronym" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "description": "Object with document fields and their respective values.", "additionalProperties": true, "properties": { "{fieldName}": { "type": "string", "description": "Field name.", "example": "{fieldValue}" } } }, "example": { "Boolean": true, "Currency": 2.5, "Date": "1992-11-17", "Date_Time": "2016-09-14T19:21:01.3163733Z", "Decimal": 2.5, "Email": "meu@email.com", "Integer": 1000000, "Long": 1000000000, "Percent": 85.42, "Time": "23:50", "URL": "http://www.vtex.com", "Varchar10": "Lorem ipsu", "Varchar50": "Lorem ipsum dolor sit amet, consectetur adipiscing", "Varchar750": "Lorem ipsum dolor sit amet, consectetur adipiscing elit...", "Varchar100": "Lorem ipsum dolor sit amet, consectetur adipiscing elit...", "Relationship": "5eb31afb-7ab0-11e6-94b4-0a44686e393f", "Text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit..." } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdHrefDocumentID" }, "example": { "id": "CL-be30ed0b-78ec-11ee-83ab-0eca8d1868e1", "href": "http://apiexamples.vtexcommercestable.com.br/api/dataentities/CL/documents/be30ed0b-78ec-11ee-83ab-0eca8d1868e1", "documentId": "be30ed0b-78ec-11ee-83ab-0eca8d1868e1" } } } } } }, "patch": { "tags": [ "Documents" ], "summary": "Create partial document", "description": "Creates a partial document, sending only some of the fields.\r\n\r\n> You can use this request to create 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\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 | **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": "Createorupdatepartialdocument", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/acronym" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "description": "Unique identifier of the document to be created.", "example": "4e4c55ac-e491-11e6-94f4-0ac138d2d42e" }, "{fieldName}": { "type": "string", "description": "Field(s) to be filled in and its respective value(s).", "example": "{fieldValue}" } } }, "example": { "id": "4e4c55ac-e491-11e6-94f4-0ac138d2d42e", "addressName": "4726026151251" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdHrefDocumentID" }, "example": { "id": "CL-be30ed0b-78ec-11ee-83ab-0eca8d1868e1", "href": "http://apiexamples.vtexcommercestable.com.br/api/dataentities/CL/documents/be30ed0b-78ec-11ee-83ab-0eca8d1868e1", "documentId": "be30ed0b-78ec-11ee-83ab-0eca8d1868e1" } } } }, "304": { "description": "Not Modified" } } } }, "/api/dataentities/{acronym}/documents/{id}": { "get": { "tags": [ "Documents" ], "summary": "Get document", "description": "Retrieves a document.\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": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/acronym" }, { "$ref": "#/components/parameters/id" }, { "$ref": "#/components/parameters/fields" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" }, "example": { "id": "2f5dde81-1613-11ea-82ee-12f868feb457", "accountId": "a8b27fb4-6516-4cc0-82b6-a5f2b011e6e2", "accountName": "apiexamples", "dataEntityId": "AS" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "description": "Error response body.", "type": "object", "properties": { "Message": { "description": "Error message.", "type": "string" } } }, "example": { "Message": "Cannot read private fields" } } } } } }, "put": { "tags": [ "Documents" ], "summary": "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.\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\n## Custom field types\r\n\r\nThe table below presents the types of custom fields you can use when creating or updating documents in Master Data v1 and example values.\r\n\r\n| Field Type| Example value |\r\n| - | - |\r\n| Boolean | `true` |\r\n| Currency | `2.5` |\r\n| Date | `1992-11-17` |\r\n| Date_Time | `2016-09-14T19:21:01.3163733Z` |\r\n| Decimal | `2.5` |\r\n| Email | `meu@email.com` |\r\n| Integer | `1000000` |\r\n| Long | `1000000000` |\r\n| Percent | `85.42` |\r\n| Time | `23:50` |\r\n| URL | `https://www.vtex.com` |\r\n| Varchar10 | `Lorem ipsu` |\r\n| Varchar50 | `Lorem ipsum dolor sit amet, consectetur adipiscing` |\r\n| Varchar750 | `Lorem ipsum dolor sit amet, consectetur adipiscing elit...` |\r\n| Varchar100 | `Lorem ipsum dolor sit amet, consectetur adipiscing elit...` |\r\n| Relationship | `5eb31afb-7ab0-11e6-94b4-0a44686e393f` |\r\n| Text | `Lorem ipsum dolor sit amet, consectetur adipiscing elit...` |\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 | **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": "Updateentiredocument", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/acronym" }, { "$ref": "#/components/parameters/id" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "description": "Object with document fields and their respective values.", "additionalProperties": true, "properties": { "{fieldName}": { "type": "string", "description": "Field name and value.", "example": "{fieldValue}" } } }, "example": { "Boolean": true, "Currency": 2.5, "Date": "1992-11-17", "Date_Time": "2016-09-14T19:21:01.3163733Z", "Decimal": 2.5, "Email": "meu@email.com", "Integer": 1000000, "Long": 1000000000, "Percent": 85.42, "Time": "23:50", "URL": "http://www.vtex.com", "Varchar10": "Lorem ipsu", "Varchar50": "Lorem ipsum dolor sit amet, consectetur adipiscing", "Varchar750": "Lorem ipsum dolor sit amet, consectetur adipiscing elit...", "Varchar100": "Lorem ipsum dolor sit amet, consectetur adipiscing elit...", "Relationship": "5eb31afb-7ab0-11e6-94b4-0a44686e393f", "Text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit..." } } }, "required": true }, "responses": { "204": { "description": "No Content" } } }, "patch": { "tags": [ "Documents" ], "summary": "Update partial document", "description": "Updates a subset of fields of a document, without impacting the other fields.\r\n\r\n>ℹ️ You can use this request to 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\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 | **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": "Updatepartialdocument", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/acronym" }, { "$ref": "#/components/parameters/id" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "description": "Object with the fields to be updated and their respective values." }, "example": { "addressName": "4726026151253" } } }, "required": true }, "responses": { "204": { "description": "No Content" } } }, "delete": { "tags": [ "Documents" ], "summary": "Delete document", "description": "Deletes a document. \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 | **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": "Deletedocument", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/acronym" }, { "$ref": "#/components/parameters/id" } ], "responses": { "204": { "description": "No Content" } } } }, "/api/dataentities/{acronym}/delete": { "post": { "tags": [ "Bulk deletion" ], "summary": "Create bulk document deletion job", "description": "Creates an asynchronous job that deletes all documents in a data entity that match a given filter.\r\n\r\n> ⚠️ This feature is in closed beta, meaning only specific customers can access it now. If you want to implement it in the future, please contact [our Support](https://support.vtex.com/hc/en-us/).\r\n\r\nThis 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/masterdata-api#get-/api/dataentities/-acronym-/delete/jobs/-jobId-) endpoint.\r\n\r\n>❗ This action cannot be undone. Deleted documents will be permanently lost.\r\n\r\n## Filter rules\r\n\r\n- The `filter` field is required.\r\n- Wildcards are not allowed. For example, `email = *@gmail.com` is rejected.\r\n- Every field used in the filter must be indexed. Internal fields, such as `createdIn`, are already indexed. A field is indexed when it exists in the data entity and has `isSearchable` enabled.\r\n- Filtering on a custom field also requires sending the `schema` that declares it as indexed in the request body.\r\n- Only one active job per account and data entity is allowed at a time.\r\n\r\n>ℹ️ 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.\r\n\r\n## Errors\r\n\r\n`{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.\r\n\r\n| Status code | Message or cause | What to do |\r\n| - | - | - |\r\n| `400` | `The 'filter' field is required` | Send the `filter` field in the body. |\r\n| `400` | `Wildcard filters are not allowed for bulk delete` | Rewrite the filter using exact or range conditions over indexed fields. |\r\n| `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. |\r\n| `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. |\r\n| `400` | `The field '{field}' does not exist for the data entity '{entity}'` | Correct the field name in the filter. |\r\n| `400` | `The field {field} of the data entity {entity} is not indexed (isSearchable is not enabled)...` (truncated) | Enable `isSearchable` on the field and wait for reindexing, or use another indexed field. |\r\n| `400` | `Invalid data entity name` | Correct the data entity name in the URL. Invalid characters are rejected. |\r\n| `409` | `Bulk deletion job creation failed for {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. |\r\n| `415` | No body was sent. | Send a JSON body with the `Content-Type: application/json` header. |\r\n| `5xx` | Transient infrastructure failure during job creation. | No residual state is left behind, so you can resend the request. |\r\n\r\n## Permissions\r\n\r\nThis request requires a valid [user token](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens), sent in the `VtexIdclientAutCookie` header.", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/acronym" }, { "name": "an", "in": "query", "description": "Name of the VTEX account that owns the data entity (for example, `apiexamples`).", "required": true, "style": "form", "schema": { "type": "string", "example": "apiexamples" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDeletionRequest" }, "examples": { "internalField": { "summary": "Filter on an internal field", "value": { "filter": "createdIn > 2026-08-16" } }, "customField": { "summary": "Filter on a custom indexed field, which requires the schema name", "value": { "filter": "number = 1337", "schema": "indexed-fields" } } } } }, "required": true }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDeletionJobResponse" }, "example": { "JobId": "01M08C83Z5D91S3CA0A15SRNV8" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDeletionErrorResponse" }, "examples": { "missingFilter": { "summary": "The filter field was not sent", "value": { "Message": "The 'filter' field is required" } }, "wildcardFilter": { "summary": "The filter uses a wildcard", "value": { "Message": "Wildcard filters are not allowed for bulk delete" } }, "schemaRequired": { "summary": "The filter uses a custom field and no schema was sent", "value": { "Message": "The field 'number' is not an internal indexed field, so the 'schema' that declares it as indexed must be provided" } }, "fieldDoesNotExist": { "summary": "The filter uses a field that does not exist in the data entity", "value": { "Message": "The field 'number' does not exist for the data entity 'SP'" } }, "invalidDataEntityName": { "summary": "The data entity name in the URL is invalid", "value": { "Message": "Invalid data entity name" } } } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDeletionErrorResponse" }, "example": { "Message": "Bulk deletion job creation failed for SP" } } } }, "415": { "description": "Unsupported Media Type" }, "500": { "description": "Internal Server Error" } } } }, "/api/dataentities/{acronym}/delete/jobs/{jobId}": { "get": { "tags": [ "Bulk deletion" ], "summary": "Get bulk document deletion job status", "description": "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/masterdata-api#post-/api/dataentities/-acronym-/delete) endpoint.\r\n\r\n> ⚠️ This feature is in closed beta, meaning only specific customers can access it now. If you want to implement it in the future, please contact [our Support](https://support.vtex.com/hc/en-us/).\r\n\r\nPoll this endpoint until the job leaves the `InProgress` status.\r\n\r\nPossible `Status` values:\r\n\r\n- `InProgress`: The job is running and documents are being deleted in batches. Keep polling and do not create another job for this data entity.\r\n- `Success`: All matching documents were deleted. Compare `DocumentsDeleted` with the number of documents you expected to delete.\r\n- `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.\r\n\r\n>ℹ️ This response contains at least the fields described in this reference. Other fields may be present, so make sure your integration ignores unexpected fields instead of failing.\r\n\r\n## Errors\r\n\r\n| Status code | Cause | What to do |\r\n| - | - | - |\r\n| `404` | The `jobId` does not exist for this account and data entity. Job records are also not kept indefinitely, so the record of an older job may no longer be available. | Check the `jobId`, the `an` query parameter, and the data entity in the URL. If all three are correct, the job is old enough that its record is no longer available. |\r\n\r\n## Permissions\r\n\r\nThis request requires a valid [user token](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens), sent in the `VtexIdclientAutCookie` header.", "parameters": [ { "$ref": "#/components/parameters/acronym" }, { "name": "jobId", "in": "path", "description": "Unique identifier of the bulk deletion job, returned by the [Create bulk document deletion job](https://developers.vtex.com/docs/api-reference/masterdata-api#post-/api/dataentities/-acronym-/delete) endpoint (for example, `01M08C83Z5D91S3CA0A15SRNV8`).", "required": true, "style": "simple", "schema": { "type": "string", "example": "01M08C83Z5D91S3CA0A15SRNV8" } }, { "name": "an", "in": "query", "description": "Name of the VTEX account that owns the data entity (for example, `apiexamples`).", "required": true, "style": "form", "schema": { "type": "string", "example": "apiexamples" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDeletionJobStatusResponse" }, "example": { "Status": "Success", "DocumentsDeleted": 1000 } } } }, "404": { "description": "Not Found" } } } }, "/api/dataentities/{acronym}/documents/{id}/versions": { "get": { "tags": [ "Versions" ], "summary": "List versions", "description": "Lists all versions of a document. \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": "Listversions", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/acronym" }, { "$ref": "#/components/parameters/id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Listversion" } }, "example": [ { "id": "_EAR0cJ7XB5k5grnmm0zeKGlVvVM9WCPV_", "date": "2016-10-18T16:53:32+00:00" }, { "id": "_E5SH9WXVvhPBNnbQtYAAGqrIysIeNYhy_", "date": "2016-09-08T20:11:42+00:00" }, { "id": "_cwVfOG7S6XeAiDBhNpLiJM1cwRiJcvdp_", "date": "2016-07-14T00:36:36+00:00" } ] } } } } } }, "/api/dataentities/{acronym}/documents/{id}/versions/{versionId}": { "get": { "tags": [ "Versions" ], "summary": "Get version", "description": "Returns the version of a document. \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": "Getversion", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/acronym" }, { "$ref": "#/components/parameters/id" }, { "name": "versionId", "in": "path", "description": "Unique identifier of the version to retrieve.", "required": true, "style": "simple", "schema": { "type": "string", "example": "_X58kLameckHYRuBMUbaimlhwqslsrrwT_" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Getversion" }, "example": { "id": "version-id", "author": "user-id", "document": { "id": "2f5dde81-1613-11ea-82ee-12f868feb457", "accountId": "a8b27fb4-6516-4cc0-82b6-a5f2b011e6e2", "accountName": "apiexamples", "dataEntityId": "AS" } } } } } } }, "put": { "tags": [ "Versions" ], "summary": "Update version", "description": "Updates the version of a document. \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 | **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": "Putversion", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/acronym" }, { "$ref": "#/components/parameters/id" }, { "name": "versionId", "in": "path", "description": "Unique identifier of the version to update.", "required": true, "style": "simple", "schema": { "type": "string", "example": "_X58kLameckHYRuBMUbaimlhwqslsrrwT_" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdHref" }, "example": { "Id": "CL-b818cbda-e489-11e6-94f4-0ac138d2d42e", "Href": "http://{{accountName}}.vtexcommercestable.com.br/api/dataentities/CL/documents/b818cbda-e489-11e6-94f4-0ac138d2d42e" } } } }, "304": { "description": "Not Modified\n\nThis response happens when the versionId informed in the path already corresponds to the current version of the document." } } } }, "/api/dataentities/{acronym}/scroll": { "get": { "tags": [ "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\n### First request example:\r\n```\r\n/dataentities/CL/scroll?isCluster=true&_size=250&_fields=email,firstName\r\n```\r\n\r\nTo inform the number of documents per request, use the query string parameter `_size`, which has the maximum value of 1000.\r\n\r\nAfter the first request, retrieve the token in the header `X-VTEX-MD-TOKEN` and make the next requests.\r\n\r\n### Example of subsequent requests:\r\n```\r\n/dataentities/CL/scroll?_token={tokenValue}\r\n```\r\n\r\n>ℹ️ Learn more about [Pagination in the Master Data API](https://developers.vtex.com/docs/guides/pagination-in-the-master-data-api).\r\n\r\n## Query examples\r\n\r\n\r\n| **Filter Type** | **Example** |\r\n|-|-|\r\n| **Simple filter** | `\/dataentities\/CL\/scroll?email=my@email.com` |\r\n| **Complex filter** | `\/dataentities\/CL\/scroll?_where=(firstName=Jon OR lastName=Smith) OR (createdIn between 2001-01-01 AND 2016-01-01)` |\r\n| **Date range** | `\/dataentities\/CL\/scroll?_where=createdIn between 2001-01-01 AND 2016-01-01` |\r\n| **Numeric field range** | `\/dataentities\/CL\/scroll?_where=age between 18 AND 25` |\r\n| **Partial filter** | `\/dataentities\/CL\/scroll?firstName=*Maria*` |\r\n| **Null values** | `\/dataentities\/CL\/scroll?_where=firstName is null` |\r\n| **Non-null values** | `\/dataentities\/CL\/scroll?_where=firstName is not null` |\r\n| **Difference** | `\/dataentities\/CL\/scroll?_where=firstName<>maria` |\r\n| **Greater than** | `\/dataentities\/CL\/scroll?_where=number>5` |\r\n| **Less than** | `\/dataentities\/CL\/scroll?_where=date<2001-01-01` |\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 `429`.\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": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/acronym" }, { "$ref": "#/components/parameters/fields" }, { "name": "_where", "in": "query", "description": "Defines a condition the document must comply with. When referring to fields, you can use a nested field up to the first level (e.g. `wishlistProduct.productName`).", "required": false, "style": "form", "schema": { "type": "string", "example": "firstName is not null" } }, { "name": "_sort", "in": "query", "description": "Defines sorting mode in two parts. The first part is the name of the field you want to sort by. It can be a nested field up to the first level (e.g. `wishlistProduct.productName`). In the second part, use `ASC` for ascending order or `DESC` for descending order.", "required": false, "style": "form", "schema": { "type": "string", "example": "firstName ASC" } }, { "name": "_size", "in": "query", "description": "Maximum amount of documents returned per request. The maximum value you can set is `1000`.", "required": false, "style": "form", "schema": { "type": "string", "example": "10" } }, { "name": "_token", "in": "query", "description": "Value of the `X-VTEX-MD-TOKEN` token obtained in the response header of the first request, necessary on subsequent requests to continue scrolling through documents. The token expires after 20 minutes of inactivity, and each request made with the token during this time resets the expiration timer.", "required": false, "style": "form", "schema": { "type": "string", "example": "123456" } } ], "responses": { "200": { "description": "OK", "headers": { "X-VTEX-MD-TOKEN": { "schema": { "type": "string", "description": "Scroll token, which must be informed in the `_token` query parameter in the subsequent requests. The token expires after 20 minutes of inactivity, and each request made with the token during this time resets the expiration timer." } }, "REST-Content-Total": { "schema": { "type": "string", "description": "Total amount of documents corresponding to the query." } } }, "content": { "application/json": { "schema": { "type": "array", "description": "List of documents.", "items": { "type": "object", "description": "Object representing each document.", "properties": { "additionalProperties": { "type": "string", "description": "Custom properties." }, "id": { "type": "string", "description": "Unique identifier of the document." }, "accountId": { "type": "string", "description": "Unique identifier of the account." }, "accountName": { "type": "string", "description": "Account name." }, "dataEntityId": { "type": "string", "description": "Two-letter string that identifies the data entity." } } } }, "example": [ { "id": "2f5dde81-1613-11ea-82ee-12f868feb457", "accountId": "a8b27fb4-6516-4cc0-82b6-a5f2b011e6e2", "accountName": "apiexamples", "dataEntityId": "AS" }, { "id": "3b3a3fc9-164b-11ea-82ee-121449f60ecb", "accountId": "a8b27fb4-6516-4cc0-82b6-a5f2b011e6e2", "accountName": "apiexamples", "dataEntityId": "AS" } ] } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "description": "Response body with error message.", "properties": { "Message": { "description": "Error message." } } }, "example": { "Message": "Maximum simultaneous scrolls rate exceeded (10)" } } } }, "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`." } } } }, "/api/dataentities/{acronym}/search": { "get": { "tags": [ "Search" ], "summary": "Search documents", "description": "Retrieves Master Data v1 documents' information, while choosing which fields will be returned and filtering documents by specific fields.\r\n\r\n>ℹ️ Learn more about [Pagination in the Master Data API](https://developers.vtex.com/docs/guides/pagination-in-the-master-data-api) and [Querying documents in Master Data v1](https://developers.vtex.com/docs/guides/querying-documents-in-master-data-v1).\r\n\r\n## Query examples\r\n\r\n\r\n| **Filter Type** | **Example** |\r\n|-|-|\r\n| **Simple filter** | `\/dataentities\/CL\/search?email=my@email.com` |\r\n| **Complex filter** | `\/dataentities\/CL\/search?_where=(firstName=Jon OR lastName=Smith) OR (createdIn between 2001-01-01 AND 2016-01-01)` |\r\n| **Date range** | `\/dataentities\/CL\/search?_where=createdIn between 2001-01-01 AND 2016-01-01` |\r\n| **Numeric field range** | `\/dataentities\/CL\/search?_where=age between 18 AND 25` |\r\n| **Partial filter** | `\/dataentities\/CL\/search?firstName=*Maria*` |\r\n| **Null values** | `\/dataentities\/CL\/search?_where=firstName is null` |\r\n| **Non-null values** | `\/dataentities\/CL\/search?_where=firstName is not null` |\r\n| **Difference** | `\/dataentities\/CL\/search?_where=firstName<>maria` |\r\n| **Greater than** | `\/dataentities\/CL\/search?_where=number>5` |\r\n| **Less than** | `\/dataentities\/CL\/search?_where=date<2001-01-01` |\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## 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": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "name": "REST-Range", "in": "header", "description": "Specifies the range of documents to be returned in the response. The value should follow the format `resources={x}-{y}`, 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\nThis field controls pagination by defining the subset of documents to be retrieved. The maximum number of documents returned per query is limited to 100.\nFor example, `resources=0-10` returns the first 10 documents.", "required": true, "style": "simple", "schema": { "type": "string", "example": "resources=0-10" } }, { "$ref": "#/components/parameters/acronym" }, { "$ref": "#/components/parameters/fields" }, { "name": "_where", "in": "query", "description": "Defines a condition the document must comply with. When referring to fields, you can use a nested field up to the first level (e.g. `wishlistProduct.productName`).", "required": false, "style": "form", "schema": { "type": "string", "example": "firstName is not null" } }, { "name": "_sort", "in": "query", "description": "Defines sorting mode in two parts. The first part is the name of the field you want to sort by. It can be a nested field up to the first level (e.g. `wishlistProduct.productName`). In the second part, use `ASC` for ascending order or `DESC` for descending order.", "required": false, "style": "form", "schema": { "type": "string", "example": "firstName ASC" } } ], "responses": { "200": { "description": "OK", "headers": { "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" } } }, "content": { "application/json": { "schema": { "type": "array", "description": "List of documents.", "items": { "type": "object", "description": "Object representing each document.", "properties": { "additionalProperties": { "type": "string", "description": "Custom properties." }, "id": { "type": "string", "description": "Unique identifier of the document." }, "accountId": { "type": "string", "description": "Unique identifier of the account." }, "accountName": { "type": "string", "description": "Account name." }, "dataEntityId": { "type": "string", "description": "Two-letter string that identifies the data entity." } } } }, "example": [ { "id": "2f5dde81-1613-11ea-82ee-12f868feb457", "accountId": "a8b27fb4-6516-4cc0-82b6-a5f2b011e6e2", "accountName": "apiexamples", "dataEntityId": "AS" }, { "id": "3b3a3fc9-164b-11ea-82ee-121449f60ecb", "accountId": "a8b27fb4-6516-4cc0-82b6-a5f2b011e6e2", "accountName": "apiexamples", "dataEntityId": "AS" } ] } } }, "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`." } } } }, "/api/dataentities/{acronym}/documents/{id}/{field}/attachments/{file-name}": { "get": { "tags": [ "Attachments" ], "summary": "Retrieve attachment", "description": "Retrieves a file that had been previously saved in a field of type `File`.\r\n\r\n>⚠️ Make sure to include the file extension in the name, like in this example: `/api/dataentities/CL/documents/123/file/attachments/image.png`. \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": "Retrieveattachment", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/acronym" }, { "$ref": "#/components/parameters/id" }, { "name": "field", "in": "path", "description": "Name of the field where the file is saved, as it appears on VTEX Admin.", "required": true, "style": "simple", "schema": { "type": "string", "example": "image" } }, { "name": "file-name", "in": "path", "description": "File name and extension.", "required": true, "style": "simple", "schema": { "type": "string", "example": "image.png" } } ], "responses": { "200": { "description": "OK", "content": { "image/jpg": { "schema": { "type": "string", "format": "binary", "description": "Image file." }, "example": "binary image data" } } } } } }, "/api/dataentities/{acronym}/documents/{id}/{field}/attachments": { "post": { "tags": [ "Attachments" ], "summary": "Save attachment", "description": "Saves a file in a field of type `File`. Learn more about [Data entity field types](https://help.vtex.com/en/tutorial/creating-data-entity--tutorials_1265#understanding-the-types).`\n\r\n\r> You can upload more than one file. Just add a new field in the `form-data` with type `File`. \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 | **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": "Saveattachment", "parameters": [ { "$ref": "#/components/parameters/Content-Type-img" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/acronym" }, { "$ref": "#/components/parameters/id" }, { "name": "field", "in": "path", "description": "Name of the field to attach the file to, as it appears in VTEX Admin.", "required": true, "style": "simple", "schema": { "type": "string", "example": "profilePicture" } } ], "requestBody": { "content": { "multipart/form-data": { "encoding": {}, "schema": { "required": [ "file" ], "type": "object", "properties": { "file": { "type": "array", "description": "Files to be uploaded.", "items": { "type": "string", "format": "binary", "description": "File to be uploaded." } } } }, "example": { "file": ["image.jpg"] } } }, "required": false }, "responses": { "204": { "description": "No Content" } } } }, "/api/dataentities/{acronym}/documents/{id}/clusters": { "post": { "tags": [ "Clusters" ], "summary": "Validate document by clusters", "description": "Validate documents by clusters.\n\r\n\r> Learn more about Master Data [clusters](https://help.vtex.com/en/tutorial/how-can-i-create-cluster-of-customers--frequentlyAskedQuestions_1724). \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 | **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": "ValidateDocumentbyClusters", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/acronym" }, { "$ref": "#/components/parameters/id" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "description": "Array of clusters.", "items": { "type": "object", "description": "Cluster information.", "properties": { "name": { "type": "string", "description": "Cluster validation rule name.", "example": "male" }, "rule": { "type": "string", "description": "Cluster validation rule.", "example": "gender=male" } } } }, "example": [ { "name": "male", "rule": "gender=male" }, { "name": "complex", "rule": "((gender=male AND percent=0.35) AND any is null) AND (name=*go*)" }, { "name": "complex2", "rule": "((gender=male AND percent=0.35) AND any is not null) OR (name=*go*)" }, { "name": "createdIn", "rule": "createdIn between 2015-10-28 AND 2015-10-30" } ] } }, "required": true }, "responses": { "200": { "description": "OK" } } } }, "/api/dataentities/{acronym}/documents/{id}/score": { "put": { "tags": [ "Score" ], "summary": "Update scores", "description": "Updates the score of more than one `Score2` type field and more than one key. Learn more about [Data entity field types](https://help.vtex.com/en/tutorial/creating-data-entity--tutorials_1265#understanding-the-types). \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 | **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": "Putscores", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/acronym" }, { "$ref": "#/components/parameters/id" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PutscoresRequest" } }, "example": [ { "field": "carttag", "key": "Payment", "point": 1, "until": "10m" }, { "field": "scoretest", "key": "Point 1", "point": 1, "until": "1d" } ] } }, "required": true }, "responses": { "204": { "description": "No Content" } } } }, "/api/dataentities/{acronym}/documents/{id}/score/{field-name}": { "put": { "tags": [ "Score" ], "summary": "Update score by field", "description": "Updates the score of a specific `Score2` type field. Learn more about [Data entity field types](https://help.vtex.com/en/tutorial/creating-data-entity--tutorials_1265#understanding-the-types). \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 | **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": "Putscorebyfield", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/acronym" }, { "name": "id", "in": "path", "description": "Unique identifier of the document.", "required": true, "style": "simple", "schema": { "type": "string", "example": "SP-b818cbda-e489-11e6-94f4-0ac138d2d42e" } }, { "name": "field-name", "in": "path", "description": "Name of the field to score.", "required": true, "style": "simple", "schema": { "type": "string", "example": "carttag" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutscorebyfieldRequest" }, "example": { "key": "first key", "point": 1, "until": "10m" } } }, "required": true }, "responses": { "204": { "description": "No Content" } } }, "delete": { "tags": [ "Score" ], "summary": "Delete score by field", "description": "Removes a key from a specific `Score2` type field. Learn more about [Data entity field types](https://help.vtex.com/en/tutorial/creating-data-entity--tutorials_1265#understanding-the-types). \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 | **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": "Deletescorebyfield", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/acronym" }, { "$ref": "#/components/parameters/id" }, { "name": "field-name", "in": "path", "description": "Name of the field to remove a key from.", "required": true, "style": "simple", "schema": { "type": "string", "example": "carttag" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletescorebyfieldRequest" }, "example": { "key": "first key" } } }, "required": true }, "responses": { "204": { "description": "No Content" } } } }, "/api/dataentities/CL/documents": { "post": { "tags": [ "Customer profiles" ], "summary": "Create new customer profile", "description": "Creates new customer profile.\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 | **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": "CreateNewCustomerProfilev2", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/_schema" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createUpdateProfileRequests" }, "example": { "email": "clark.kent@examplemail.com", "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/documentResponse" }, "example": { "Id": "CL-b818cbda-e489-11e6-94f4-0ac138d2d42e", "Href": "http://api.vtex.com/my-store-name/dataentities/CL/documents/b818cbda-e489-11e6-94f4-0ac138d2d42e" } } } } } } }, "/api/dataentities/CL/documents/{id}": { "patch": { "tags": [ "Customer profiles" ], "summary": "Update customer profile", "description": "Partially updates a customer profile.\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 | **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": "UpdateCustomerProfile", "parameters": [ { "$ref": "#/components/parameters/_schema" }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createUpdateProfileRequests" }, "example": { "email": "clark.kent@examplemail.com", "firstName": "Clark", "lastName": "Kent" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/documentResponse" }, "example": { "Id": "CL-b818cbda-e489-11e6-94f4-0ac138d2d42e", "Href": "http://api.vtex.com/my-store-name/dataentities/CL/documents/b818cbda-e489-11e6-94f4-0ac138d2d42e" } } } } } }, "delete": { "tags": [ "Customer profiles" ], "summary": "Delete customer profile", "description": "Deletes a customer profile. \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 | **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": "DeleteCustomerProfile", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/id" } ], "responses": { "204": { "description": "No Content" } } } }, "/api/dataentities/AD/documents": { "post": { "tags": [ "Addresses" ], "summary": "Create new customer address", "description": "Creates new customer address. \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 | **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": "CreateNewCustomerAddress", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/_schema" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createUpdateAddressRequests" }, "example": { "addressName": "My house", "addressLabel": "NC Office", "addressType": "commercial", "receiverName": "Clark Kent", "city": "Raleigh", "state": "NC", "country": "USA", "postalCode": "12345", "street": "Main Street", "number": "300", "neighborhood": "Downtown", "complement": "3rd floor", "reference": "Next to the park", "geoCoordinate": "40.7128,-74.0060", "userId": "7e03m794-a33a-11e9-84rt6-0adfa64s5a8e" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/documentResponse" }, "example": { "Id": "AD-b818cbda-e489-11e6-94f4-0ac138d2d42e", "Href": "http://api.vtex.com/my-store-name/dataentities/AD/documents/b818cbda-e489-11e6-94f4-0ac138d2d42e" } } } } } } }, "/api/dataentities/AD/documents/{addressId}": { "get": { "tags": [ "Addresses" ], "summary": "Get address by ID", "description": "This endpoint retrieves information of a specific address by its unique identifier.\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.", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "name": "addressId", "in": "path", "description": "ID of the address to retrieve.", "required": true, "schema": { "type": "string" }, "example": "4286e252-050b-11f0-b37f-d6617047d485" }, { "name": "_fields", "in": "query", "description": "Specifies that all fields of the document should be included in the response.", "required": true, "schema": { "type": "string", "default": "_all" }, "example": "_all" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressResponse" }, "example": { "addressLabel": "NC Office", "addressType": "commercial", "city": "Raleigh", "complement": "", "country": "USA", "countryfake": null, "geoCoordinate": "", "neighborhood": "", "number": "11", "postalCode": "48226", "receiverName": "Backpack-Klub-LLC", "reference": null, "state": "NC", "street": "Toringon Street", "userId": "2da4e9ab-050b-11f0-b37f-f4b136dbcce1", "id": "4286e252-050b-11f0-b37f-d6617047d485", "accountId": "5f1fe23b-9fd1-417d-a4aa-14df38e7746e", "accountName": "qastore", "dataEntityId": "AD", "createdBy": "c83ea7ed-f875-4a10-b0a0-98d96aedab06", "createdIn": "2025-03-19T21:44:01.4199691Z", "updatedBy": null, "updatedIn": null, "lastInteractionBy": "c83ea7ed-f875-4a10-b0a0-98d96aedab06", "lastInteractionIn": "2025-03-19T21:44:01.4199691Z", "followers": [], "tags": [], "auto_filter": null } } } } } }, "patch": { "tags": [ "Addresses" ], "summary": "Update address by ID", "description": "This endpoint allows you to update an existing address document in the `AD` data entity. Partially updates a customer address.\n\n> ⚠️ When updating addresses you must send each field according to the specifications provided. Otherwise, the Checkout module will not be able to autofill data during the shopping flow, which can block the purchase. Learn more about [SmartCheckout - Customer information automatic fill-in](https://help.vtex.com/en/tutorial/smartcheckout-preenchimento-automatico-de-dados-do-cliente--2Nuu3xAFzdhIzJIldAdtan#).\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 | **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": "UpdateCustomerAddress", "parameters": [ { "$ref": "#/components/parameters/_schema" }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "name": "addressId", "in": "path", "description": "ID of the address to update.", "required": true, "schema": { "type": "string" }, "example": "4286e252-050b-11f0-b37f-d6617047d485" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createUpdateAddressRequests" }, "example": { "addressName": "NC Office", "addressLabel": "NC Office", "postalCode": "48226", "street": "Toringon Street", "number": "11", "neighborhood": "", "complement": "", "city": "Raleigh", "state": "NC", "country": "USA", "receiverName": "Backpack-Klub-LLC", "geoCoordinate": "", "addressType": "commercial", "reference": "Grey building", "userId": "2da4e9ab-050b-11f0-b37f-d6617047d485" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/documentResponse" }, "example": { "Id": "AD-b818cbda-e489-11e6-94f4-0ac138d2d42e", "Href": "http://api.vtex.com/my-store-name/dataentities/AD/documents/b818cbda-e489-11e6-94f4-0ac138d2d42e" } } } } } }, "delete": { "tags": [ "Addresses" ], "summary": "Delete address by ID", "description": "This endpoint allows you to delete a specific address document from the `AD` data entity. Deletes a customer address.\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 | **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": "DeleteCustomerAD", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "name": "addressId", "in": "path", "description": "ID of the address to be deleted.", "required": true, "schema": { "type": "string" }, "example": "4286e252-050b-11f0-b37f-d6617047d485" } ], "responses": { "204": { "description": "No Content" } } } } }, "security": [ { "appKey": [], "appToken": [] }, { "VtexIdclientAutCookie": [] } ], "components": { "securitySchemes": { "appKey": { "type": "apiKey", "in": "header", "name": "X-VTEX-API-AppKey", "description": "Unique identifier of the [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys)." }, "appToken": { "type": "apiKey", "in": "header", "name": "X-VTEX-API-AppToken", "description": "Secret token of the [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys)." }, "VtexIdclientAutCookie": { "type": "apiKey", "in": "header", "name": "VtexIdclientAutCookie", "description": "[User token](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens), valid for 24 hours." } }, "parameters": { "Content-Type": { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, "Content-Type-img": { "name": "Content-Type", "in": "header", "description": "Type of the content being sent. If you are uploading an image, use `image/jpg` or `image/png`. When using JavaScript, use `multipart/form-data`.", "required": true, "style": "simple", "schema": { "type": "string", "example": "image/jpg" } }, "Accept": { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/vnd.vtex.ds.v10+json" } }, "acronym": { "name": "acronym", "in": "path", "description": "Two-letter string that identifies the data entity.", "required": true, "style": "simple", "schema": { "type": "string", "example": "SP" } }, "id": { "name": "id", "in": "path", "description": "Unique identifier of the document.", "required": true, "style": "simple", "schema": { "type": "string", "example": "SP-b818cbda-e489-11e6-94f4-0ac138d2d42e" } }, "fields": { "name": "_fields", "in": "query", "description": "Names of the fields that will be returned per document, separated by a comma `,`. It is possible to fetch all fields using `_all` as the value of this query parameter. However, in order to avoid permission errors, we strongly recommend informing only the names of the exact fields that will be used.", "required": false, "style": "form", "schema": { "type": "string", "example": "email,firstName,document" } }, "_schema": { "name": "_schema", "in": "query", "description": "Name of the [schema](https://developers.vtex.com/docs/guides/master-data-schema-lifecycle) that the document complies with. This field is required when using `_where` or `_fields` query parameters.", "required": false, "style": "form", "schema": { "type": "string", "example": "schema" } } }, "schemas": { "Listdataentity": { "title": "Listdataentity", "required": [ "acronym", "name", "primaryKeyType", "allowGetAll" ], "type": "object", "description": "Data entity information.", "properties": { "acronym": { "title": "acronym", "type": "string", "description": "Two-letter string that identifies the data entity." }, "name": { "title": "name", "type": "string", "description": "Data entity name." }, "primaryKeyType": { "title": "primaryKeyType", "type": "string", "description": "Primary key type." }, "allowGetAll": { "title": "allowGetAll", "type": "boolean", "description": "Defines if it will be allowed to retrieve all fields from documents from this data entity at once using the [Get document](https://developers.vtex.com/docs/api-reference/masterdata-api#get-/api/dataentities/-acronym-/documents/-id-) endpoint (`true`) or not (`false`)." } } }, "Getdataentityfields": { "title": "Data entity structure", "required": [ "acronym", "name", "primaryKeyType", "allowGetAll", "fields" ], "type": "object", "description": "Data entity structure.", "properties": { "acronym": { "$ref": "#/components/schemas/Listdataentity/properties/acronym" }, "name": { "$ref": "#/components/schemas/Listdataentity/properties/name" }, "primaryKeyType": { "$ref": "#/components/schemas/Listdataentity/properties/primaryKeyType" }, "allowGetAll": { "$ref": "#/components/schemas/Listdataentity/properties/allowGetAll" }, "fields": { "title": "fields", "type": "array", "description": "List of fields that documents from the given data entity have.", "items": { "$ref": "#/components/schemas/Field" } } } }, "Field": { "title": "Field", "description": "Field information.", "required": [ "name", "type", "displayName", "isNullable", "isSearchable", "isFilter", "isInternal" ], "type": "object", "properties": { "name": { "type": "string", "description": "Field name." }, "type": { "type": "string", "description": "Field type." }, "displayName": { "type": "string", "description": "Field display name." }, "isNullable": { "type": "boolean", "description": "Defines whether the field is nullable (`true`) or not (`false`)." }, "isSearchable": { "type": "boolean", "description": "Defines whether the field is searchable (`true`) or not (`false`)." }, "isFilter": { "type": "boolean", "description": "Defines whether the field is a filter (`true`) or not (`false`)." }, "isInternal": { "type": "boolean", "description": "Defines whether the field is for internal use only (`true`) or not (`false`)." } } }, "IdHrefDocumentID": { "type": "object", "description": "Document information.", "properties": { "id": { "type": "string", "description": "ID of the document that was created, with data entity prefix." }, "href": { "type": "string", "description": "Document reference URL." }, "documentId": { "type": "string", "description": "Unique identifier of the document." } } }, "IdHref": { "title": "IdHref", "required": [ "Id", "Href" ], "type": "object", "description": "Document information.", "properties": { "Id": { "type": "string", "description": "ID of the document that was created, with data entity prefix." }, "Href": { "type": "string", "description": "Document reference URL." } } }, "PutscoresRequest": { "title": "PutscoresRequest", "required": [ "field", "key", "point", "until" ], "type": "object", "description": "Score information.", "properties": { "field": { "type": "string", "description": "Field name.", "example": "carttag" }, "key": { "type": "string", "description": "Key name.", "example": "Payment" }, "point": { "type": "integer", "format": "int32", "description": "Amount of points to be added to the score.", "example": 1 }, "until": { "type": "string", "description": "Amount of time the added points will be valid for.", "example": "10m" } } }, "PutscorebyfieldRequest": { "title": "PutscorebyfieldRequest", "required": [ "key", "point", "until" ], "type": "object", "description": "Request body object to update score.", "properties": { "key": { "type": "string", "description": "Key name.", "example": "Payment" }, "point": { "type": "integer", "format": "int32", "description": "Amount of points to be added to the score.", "example": 1 }, "until": { "type": "string", "description": "Amount of time the added points will be valid for.", "example": "10m" } } }, "DeletescorebyfieldRequest": { "title": "DeletescorebyfieldRequest", "required": [ "key" ], "type": "object", "description": "Request body object to delete score.", "properties": { "key": { "type": "string", "description": "Key name.", "example": "Payment" } } }, "Listversion": { "title": "Listversion", "required": [ "id", "date" ], "type": "object", "description": "Version information.", "properties": { "id": { "type": "string", "description": "Unique identifier of the version." }, "date": { "type": "string", "description": "Date when the version was created, in ISO 8601 format." } } }, "Getversion": { "title": "Getversion", "required": [ "id", "author", "document" ], "type": "object", "description": "Version information.", "properties": { "id": { "type": "string", "description": "Unique identifier of the version." }, "author": { "type": "string", "description": "Unique identifier of the user who created the version." }, "document": { "$ref": "#/components/schemas/Document" } } }, "Document": { "title": "Document", "required": [ "id", "dataEntityId", "accountId", "accountName" ], "type": "object", "description": "Object representing each document.", "properties": { "{customProperty}": { "type": "string", "description": "Custom property." }, "id": { "type": "string", "description": "Unique identifier of the document." }, "accountId": { "type": "string", "description": "Unique identifier of the account." }, "accountName": { "type": "string", "description": "Account name." }, "dataEntityId": { "type": "string", "description": "Two-letter string that identifies the data entity." } } }, "createUpdateProfileRequests": { "type": "object", "description": "Request body object.", "properties": { "email": { "type": "string", "description": "Client email address. This field is required for B2B Buyer Portal.", "maxLength": 300, "example": "clark.kent@examplemail.com", "nullable": true }, "firstName": { "type": "string", "description": "Client first name. This field is required for B2B Buyer Portal.", "example": "Clark", "maxLength": 300, "nullable": true }, "lastName": { "type": "string", "description": "Client last name. This field is required for B2B Buyer Portal.", "example": "Kent", "maxLength": 300, "nullable": true }, "phone": { "type": "string", "description": "Client telephone number.", "example": "+12025550195", "nullable": true }, "documentType": { "type": "string", "description": "Client document type. This field is required for B2B Buyer Portal.", "maxLength": 300, "example": "CPF", "nullable": true }, "document": { "type": "string", "description": "Client document. This field is required for B2B Buyer Portal.", "example": "12345678900", "maxLength": 300, "nullable": true }, "isCorporate": { "type": "boolean", "description": "Indicates whether client is corporate. For the B2B Buyer Portal, this field is required and always `true`.", "example": false, "nullable": true }, "isNewsletterOptIn": { "type": "boolean", "description": "Indicates whether client otped to receive the store newsletter (`true`) or not (`false`).", "example": false, "nullable": true }, "localeDefault": { "type": "string", "description": "Default locale, used to set store language and currency, for example.", "example": "en-US", "nullable": true }, "corporateDocument": { "type": "string", "maxLength": 300, "description": "The business document of the contract. This field is recommended for B2B Buyer Portal." }, "homePhone": { "type": "string", "maxLength": 300, "description": "The home phone number of the contract. This field is recommended for B2B Buyer Portal." }, "cellPhone": { "type": "string", "maxLength": 300, "description": "The cell phone number of the contract. This field is recommended for B2B Buyer Portal." }, "corporateName": { "type": "string", "maxLength": 300, "description": "The corporate name of the contract. This field is required for B2B Buyer Portal." }, "tradeName": { "type": "string", "maxLength": 300, "description": "The trade name (\"doing business as\") of the contract. This field is recommended for B2B Buyer Portal." }, "stateRegistration": { "type": "string", "maxLength": 300, "description": "The state registration of the contract. This field is recommended for B2B Buyer Portal." }, "isFreeStateRegistration": { "type": "boolean", "description": "Indicates if the state registration is free. This field is recommended for B2B Buyer Portal." }, "priceTables": { "type": "string", "maxLength": 50, "description": "Price tables associated with the contract, separated by commas. This field is recommended for B2B Buyer Portal." }, "restrictions": { "type": "object", "description": "Object with restriction definitions for `vtex.catalog`, `vtex.checkout`, and `vtex.payments`. This field is recommended for B2B Buyer Portal.", "properties": { "vtex.catalog": { "type": "object", "description": "Object containing restrictions regarding catalog. This field is recommended for B2B Buyer Portal.", "properties": { "collectionIds": { "type": "array", "description": "A list of collection IDs that define which product collections (sets of SKUs) the B2B customer can view or purchase from. These IDs are internal catalog entities used to group products logically. This field is recommended for B2B Buyer Portal.", "items": { "type": "string", "description": "Collection ID. This field is recommended for B2B Buyer Portal." } } } }, "vtex.checkout": { "type": "object", "description": "Object containing restrictions regarding checkout. This field is recommended for B2B Buyer Portal.", "properties": { "creditCards": { "type": "array", "description": "A list of credit card IDs that the customer is allowed to use during checkout. These IDs reference cards stored in the BK entity, managed by the VTEX Checkout system. This field is recommended for B2B Buyer Portal.", "items": { "type": "string", "description": "Credit card ID. This field is recommended for B2B Buyer Portal." } } } }, "vtex.payments": { "type": "object", "description": "Contains restrictions regarding payments. This field is recommended for B2B Buyer Portal.", "properties": { "paymentSystemIds": { "type": "array", "description": "A list of numeric IDs that represent the allowed payment systems (e.g., credit card processors) for the customer. These IDs are predefined and globally recognized by VTEX. This field is recommended for B2B Buyer Portal.", "items": { "type": "string", "description": "Payment system ID. This field is recommended for B2B Buyer Portal." } } } } } } } }, "createUpdateAddressRequests": { "type": "object", "description": "Request body object.", "properties": { "addressName": { "type": "string", "description": "Address name.", "example": "My house", "nullable": true }, "addressLabel": { "type": "string", "description": "Custom label for the address used by shoppers and buyer org managers.", "example": "NC Office", "nullable": true }, "addressType": { "type": "string", "description": "Type of address. For example, `Residential` or `Pickup`, among others. For B2B Buyer Portal, this field is required and its possible values are `commercial` for shipping or `invoice` for billing.", "enum": [ "commercial", "invoice" ], "example": "commercial", "nullable": true }, "receiverName": { "type": "string", "description": "Name of the person who is going to receive orders at this address. This field is required for B2B Buyer Portal.", "example": "Clark Kent.", "nullable": true }, "city": { "type": "string", "description": "City of the shipping address. This field is required for B2B Buyer Portal.", "example": "Raleigh", "nullable": true }, "state": { "type": "string", "description": "State of the shipping address. The state or province of the address. This field is required for B2B Buyer Portal.", "example": "NC", "nullable": true }, "country": { "type": "string", "description": "Three letter ISO code of the country of the shipping address. This field is required for B2B Buyer Portal.", "example": "USA", "nullable": true }, "postalCode": { "type": "string", "description": "Postal Code. The format must be compatible with the country postal code format (e.g., `00000` for addresses in the USA). This field is required for B2B Buyer Portal.", "example": "12345", "nullable": true }, "street": { "type": "string", "description": "The street name of the address. This field is required for B2B Buyer Portal.", "example": "Main Street", "nullable": true }, "number": { "type": "string", "description": "Number of the building, house or apartment in the shipping address. This field is required for B2B Buyer Portal.", "example": "300", "nullable": true }, "neighborhood": { "type": "string", "description": "Neighborhood of the address.", "example": "Downtown", "nullable": true }, "complement": { "type": "string", "description": "Additional information or details that help identify or locate the shipping address, such as apartment number, suite, floor, or unit (if applicable).", "example": "3rd floor", "nullable": true }, "reference": { "type": "string", "description": "Optional reference point or nearby landmark to help locate the shipping address during delivery (e.g., next to a park or behind a building).", "example": "Next to the park", "nullable": true }, "geoCoordinate": { "type": "string", "description": "The geographical coordinates of the address (optional). This field is recommended for B2B Buyer Portal.", "example": "40.7128,-74.0060", "nullable": true }, "userId": { "type": "string", "description": "ID of the customer to whom the address belongs. This information is the `id` returned by the customer profile (or contract) creation request. This field is required for B2B Buyer Portal.", "example": "7e03m794-a33a-11e9-84rt6-0adfa64s5a8e", "nullable": true } } }, "documentResponse": { "required": [ "Id", "Href" ], "type": "object", "description": "Response body object.", "properties": { "Id": { "type": "string", "description": "ID of the document that was created or updated." }, "Href": { "type": "string", "description": "Document reference URL." } } }, "CreateAddressResponse": { "type": "object", "description": "Response body for a created address.", "properties": { "Id": { "type": "string", "description": "The prefixed ID of the document." }, "Href": { "type": "string", "description": "The URL to access the created document." }, "DocumentId": { "type": "string", "description": "The actual document ID ([UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier)) within the entity." } } }, "AddressResponse": { "type": "object", "description": "Response body for an address document.", "properties": { "addressLabel": { "type": "string", "nullable": true, "description": "A user-defined label to identify the address." }, "addressType": { "type": "string", "nullable": true, "description": "The type of address: `commercial` for shipping, `invoice` for billing.", "enum": [ "commercial", "invoice" ] }, "city": { "type": "string", "nullable": true, "description": "The city of the address." }, "complement": { "type": "string", "nullable": true, "description": "Any additional information for the address (e.g., apartment, floor)." }, "country": { "type": "string", "nullable": true, "description": "The country of the address in three-letter code format (e.g., `\"USA\"`)." }, "countryfake": { "type": "string", "nullable": true, "description": "Placeholder or optional country value." }, "geoCoordinate": { "type": "string", "nullable": true, "description": "Geographical coordinates of the address (latitude and longitude)." }, "neighborhood": { "type": "string", "nullable": true, "description": "The neighborhood of the address." }, "number": { "type": "string", "nullable": true, "description": "The street number of the address." }, "postalCode": { "type": "string", "nullable": true, "description": "The postal code of the address. The format must be compatible with the address country postal code format. (e.g., `00000` for addresses in the USA)." }, "receiverName": { "type": "string", "nullable": true, "description": "The name of the person or entity receiving at this address." }, "reference": { "type": "string", "nullable": true, "description": "Optional reference point or landmark near the address." }, "state": { "type": "string", "nullable": true, "description": "The state or province of the address." }, "street": { "type": "string", "nullable": true, "description": "The street name of the address." }, "userId": { "type": "string", "nullable": true, "description": "The ID of the user or related entity." }, "id": { "type": "string", "nullable": true, "description": "Unique identifier for this address record." }, "accountId": { "type": "string", "nullable": true, "description": "ID of the account related to this address." }, "accountName": { "type": "string", "nullable": true, "description": "Name of the account related to this address." }, "dataEntityId": { "type": "string", "nullable": true, "description": "ID of the data entity this address belongs to (always `\"AD\"`)." }, "createdBy": { "type": "string", "nullable": true, "description": "ID of the user who created the address record." }, "createdIn": { "type": "string", "nullable": true, "description": "Timestamp of when the address record was created." }, "updatedBy": { "type": "string", "nullable": true, "description": "ID of the user who last updated the address record." }, "updatedIn": { "type": "string", "nullable": true, "description": "Timestamp of the last update to the address record." }, "lastInteractionBy": { "type": "string", "nullable": true, "description": "ID of the user who had the last interaction with the record." }, "lastInteractionIn": { "type": "string", "nullable": true, "description": "Timestamp of the last interaction with the record." }, "followers": { "type": "array", "nullable": true, "description": "List of users following this address record.", "items": { "type": "string", "description": "User ID." } }, "tags": { "type": "array", "nullable": true, "description": "List of tags associated with this address.", "items": { "type": "string", "description": "Tag value." } }, "auto_filter": { "type": "string", "nullable": true, "description": "Optional field used for automatic filtering or categorization." } } }, "BulkDeletionRequest": { "type": "object", "description": "Request body object.", "required": [ "filter" ], "properties": { "filter": { "type": "string", "description": "Deletion criteria, using the same syntax as the filter in the [Search documents](https://developers.vtex.com/docs/api-reference/masterdata-api#get-/api/dataentities/-acronym-/search) request. Wildcards are not allowed and every field must be indexed." }, "schema": { "type": "string", "description": "Name of the [schema](https://developers.vtex.com/docs/guides/master-data-schema-lifecycle) that declares the filtered field as indexed. Required only when the filter uses custom fields." } } }, "BulkDeletionJobResponse": { "type": "object", "description": "Response body object.", "properties": { "JobId": { "type": "string", "description": "Unique identifier of the bulk deletion job. Use this value to track the job with the [Get bulk document deletion job status](https://developers.vtex.com/docs/api-reference/masterdata-api#get-/api/dataentities/-acronym-/delete/jobs/-jobId-) endpoint." } } }, "BulkDeletionJobStatusResponse": { "type": "object", "description": "Response body object.", "additionalProperties": true, "properties": { "Status": { "type": "string", "description": "Current status of the bulk deletion job. Possible values: `InProgress`, `Success`, or `Failed`.", "enum": [ "InProgress", "Success", "Failed" ] }, "DocumentsDeleted": { "type": "integer", "description": "Number of documents that the job has deleted." } } }, "BulkDeletionErrorResponse": { "type": "object", "description": "Response body object.", "properties": { "Message": { "type": "string", "description": "Error message." } } } } }, "tags": [ { "name": "Data entities" }, { "name": "Documents" }, { "name": "Customer profiles" }, { "name": "Addresses" }, { "name": "Versions" }, { "name": "Scroll" }, { "name": "Search" }, { "name": "Attachments" }, { "name": "Clusters" }, { "name": "Score" }, { "name": "Bulk deletion", "description": "Bulk deletion removes all documents in a data entity that match a filter, through an asynchronous job. This action cannot be undone." } ] }