Master Data API - v1
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.
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.
Index
Data Entities
Obtain information about the structure of the data entities.
Documents
Create, update and retrieve documents.
POSTCreate new documentPUTCreate document with custom ID or Update entire documentPATCHCreate or update partial documentGETGet documentPUTUpdate entire documentPATCHUpdate partial documentDELETEDelete document
Customer profiles
Modify customer profiles in the CL entity.
POSTCreate new customer profilePATCHUpdate customer profileDELETEDelete customer profile
Addresses
Modify customer addresses in the AD entity.
POSTCreate new customer addressPATCHUpdate customer addressDELETEDelete customer address
Versions
Master Data documents are versioned. This means that, for each change, a new version is generated. The versions endpoints allow you to query the versions and also apply the state of a document to the most current version.
GETList versionsGETGet versionPUTPut version
Scroll
Developed for external integration scenarios. If your collection is over 10.000 documents or you need to query the entire VTEX Master Data database, use these endpoints.
GETScroll documents
Search
Query a collection of documents.
GETSearch documents
Attachments
Upload and download files.
GETRetrieve attachmentPOSTSave attachment
Clusters
Check if a particular document is in one or more clusters.
Score
Record and remove points in Score2 type fields. Learn more about Data entity field types.
PUTPut scoresPUTPut score by fieldDELETEDelete score by field
Endpoints
Data entities
| Summary | Method | Path |
|---|---|---|
| List data entities | GET | /api/dataentities |
| Get data entity structure | GET | /api/dataentities/{acronym} |
Documents
| Summary | Method | Path |
|---|---|---|
| Create new document | POST | /api/dataentities/{acronym}/documents |
| Create partial document | PATCH | /api/dataentities/{acronym}/documents |
| Get document | GET | /api/dataentities/{acronym}/documents/{id} |
| Create document with custom ID or update entire document | PUT | /api/dataentities/{acronym}/documents/{id} |
| Update partial document | PATCH | /api/dataentities/{acronym}/documents/{id} |
| Delete document | DELETE | /api/dataentities/{acronym}/documents/{id} |
Customer profiles
| Summary | Method | Path |
|---|---|---|
| Create new customer profile | POST | /api/dataentities/CL/documents |
| Update customer profile | PATCH | /api/dataentities/CL/documents/{id} |
| Delete customer profile | DELETE | /api/dataentities/CL/documents/{id} |
Addresses
| Summary | Method | Path |
|---|---|---|
| Create new customer address | POST | /api/dataentities/AD/documents |
| Get address by ID | GET | /api/dataentities/AD/documents/{addressId} |
| Update address by ID | PATCH | /api/dataentities/AD/documents/{addressId} |
| Delete address by ID | DELETE | /api/dataentities/AD/documents/{addressId} |
Versions
| Summary | Method | Path |
|---|---|---|
| List versions | GET | /api/dataentities/{acronym}/documents/{id}/versions |
| Get version | GET | /api/dataentities/{acronym}/documents/{id}/versions/{versionId} |
| Update version | PUT | /api/dataentities/{acronym}/documents/{id}/versions/{versionId} |
Scroll
| Summary | Method | Path |
|---|---|---|
| Scroll documents | GET | /api/dataentities/{acronym}/scroll |
Search
| Summary | Method | Path |
|---|---|---|
| Search documents | GET | /api/dataentities/{acronym}/search |
Attachments
| Summary | Method | Path |
|---|---|---|
| Retrieve attachment | GET | /api/dataentities/{acronym}/documents/{id}/{field}/attachments/{file-name} |
| Save attachment | POST | /api/dataentities/{acronym}/documents/{id}/{field}/attachments |
Clusters
| Summary | Method | Path |
|---|---|---|
| Validate document by clusters | POST | /api/dataentities/{acronym}/documents/{id}/clusters |
Score
| Summary | Method | Path |
|---|---|---|
| Update scores | PUT | /api/dataentities/{acronym}/documents/{id}/score |
| Update score by field | PUT | /api/dataentities/{acronym}/documents/{id}/score/{field-name} |
| Delete score by field | DELETE | /api/dataentities/{acronym}/documents/{id}/score/{field-name} |