API Reference

Master DataHow it works

This article explains the Master Data core components: Data Entity, Document, Field and Index.

The Master Data core components are equivalent to what is found in database solutions. Some of these components might be found in common database solutions with other names such as record or table.

Data Entity

In comparison to a regular database, Data Entity is a table in which records (or Documents) and Fields are always stored.

Master Data currently has two versions (V1 and V2). In V1, a Data Entity is referred by its acronym (a sequence of two uppercase characters). In V2, it is used the name of the Data Entity for reference. For instance, in Master Data V1 Data Entities can be called CL or AD, while in Master Data V2 Data Entities can be called Client and Address.

While the CL Data Entity is used to keep all customer data related to personal information such as name, email, document and others stored in the same place, the AD Data Entity is used to store all customers addresses with their respective information such as: receiver name, street, city, etc.


A Document is a record (a row of the table) inside a Data Entity with an identifier (a Field named id). Inside CL Data Entity, for example, each person is represented by a document that has an id and other information.


Documents are composed by one or more Fields (attributes) that specifies characteristics of the Data Entity record. Fields can also be considered as the columns of a Data Entity table. For example, the CL Data Entity has Fields to store the customer's name, email, birth date and document number.

Data has a shape. A name field is usually expressed as string type, whereas in age is used an integer number type. You can configure the shape of your data for each Data Entity to guarantee consistency. In other words, every Document follows the shape defined by the Data Entity in which it is inserted and its Fields.

Meaning that each Field has a Type which indicates the format of the attribute being string, number, date, null, object or array.


An Index is a shortcut to find Documents whenever users do not know the Document id. An Index can be set up for each Field of a Data Entity. As well as when using an id, the Index is used to retrieve a single Document at a time, but using the value of indexed Field instead. For instance, users can find a Document inside CL Data Entity through the email because it has a native Index for the email Field. Indexes are set up in Master Data V1 using the Admin and in Master Data V2 through the API.

The Index of a Document is created when the Document is created or modified. Documents will only have Index if the creation or change occurs after the Index of the Data Entity was set up. Documents created before the Index set up of the Data Entity need to be updated to receive the Index. After a Document has an Index, you can retrieve it by using the Search API with the Field name as a query parameter and the value of Field as the value of the parameter. Example: /dataentities/CL/search?

Photo of the contributor
+ 1 contributors
Was this helpful?
Suggest edits (Github)
Photo of the contributor
+ 1 contributors
On this page