Documentation
Feedback
Guides
API Reference

Guides
Data Protection Plus
Profile System integration

Data Protection Plus is in closed beta phase, only available in select regions.

This feature is part of VTEX Shield. If you are already a VTEX customer and want to adopt VTEX Shield for your business, please contact Commercial Support. Additional fees may apply. If you are not yet a customer but are interested in this solution, please complete our contact form.

The Profile System is VTEX's single source of truth regarding shoppers' profile data for stores using Data Protection Plus. Other modules, such as Checkout and Order Management, can request data from the Profile System when necessary.

The Profile System API enables stores to:

  • Communicate with a single source of truth for shoppers' data.
  • Safely store PII and sensitive information.

Below you can learn more about some of the Profile System's features and how to integrate with the APIs.

Data stored in the new Profile System is not related to documents saved in Master Data v1 or Master Data v2. The API endpoints and features described in this article only apply to documents registered in the new Profile System designed to handle PII data architecture.

Before you start

Permission

To use the Profile System features, ensure you have the appropriate License Manager resources enabled for that user.

ProductCategoryResourceDescription
Profile SystemDocumentsGet ItemGet items in Profile System entities
Profile SystemDocumentsSave and Update ItemEdit items from Profile System.
Profile SystemDocumentsDelete ItemDelete items from Profile System.

Learn more about License Manager roles and resources.

Auditability

You can use the Audit app to check actions made using the Profile System in your account.

See the table below to learn more about the Profile System events available on Audit.

ActionDescriptionEvent details
GetProfileVersionUnmaskedRetrieval of an unmasked profile by ID and version.Profile ID and version ID.
EmailRectificationChange existing email address.ID of user whose email was rectified.

TTL

Profile System documents have a defined TTL, which means Time To Live. This means that whenever a customer creates a profile, it will be deleted after the TTL has passed from the time of its creation.

You may set a document's TTL, with the query parameter ttl allowed for requests that create or update documents.

Alternative keys

Shopper profiles and addresses are accessible via API by a unique profileId. However, it is also possible to use alternative keys. Currently, there are two allowed alternative keys:

  • email
  • document

Note that, in this context, the document field means the document number registered by the store customer.

To do this, you must replace the profileId path parameter with the key of your choice and send the name of the field that will be used in the query parameter alternativeKey.

Masked data

After registering customer information to the Profile System, such as profile and address, it will be returned as masked by the default GET requests.

There are specific endpoints from which to get unmasked data. When using those, mind this query parameter:

ParameterRequiredTypeDescription
reasonYesStringReason for requesting unmasked data.
Masked profile example

_17
{
_17
"id": "70caf394-8534-447e-a0ca-1803c669c771",
_17
"meta": {
_17
"version": "abc",
_17
"author": "e40e0b6d-0605-4fa6-8176-1d69fbaf0818",
_17
"creationDate": "13/12/2021T00:00:00Z",
_17
"lastUpdate": "13/12/2021T00:00:00Z"
_17
},
_17
"document": {
_17
"firstName": "J***",
_17
"lastName": "D**",
_17
"email": "j***.d**@e******.c**",
_17
"birthDate": "1925-11-17",
_17
"document": "1**********",
_17
"documentType": "CPF"
_17
}
_17
}

Unmasked profile example

_17
{
_17
"id": "70caf394-8534-447e-a0ca-1803c669c771",
_17
"document": {
_17
"firstName": "John",
_17
"lastName": "Doe",
_17
"email": "john.doe@example.com",
_17
"birthDate": "1925-11-17",
_17
"document": "12345678911",
_17
"documentType": "CPF"
_17
},
_17
"meta": {
_17
"version": "abc",
_17
"author": "e40e0b6d-0605-4fa6-8176-1d69fbaf0818",
_17
"creationDate": "13/12/2021T00:00:00Z",
_17
"lastUpdate": "13/12/2021T00:00:00Z"
_17
}
_17
}

Profile System API reference

There are several APIs you can integrate with in order to manage information regarding profiles and addresses. Below you can find some examples and links to the detailed API reference.

Profiles

A profile is the main entity where a given customer’s data is stored.

Example request body for profile creation

_10
{
_10
"firstName": "John",
_10
"lastName": "Doe",
_10
"email": "john.doe@example.com",
_10
"birthDate": "1925-11-17",
_10
"document": "12345678911",
_10
"documentType": "CPF"
_10
}

Example response when getting unmasked profile

_17
{
_17
"id": "70caf394-8534-447e-a0ca-1803c669c771",
_17
"document": {
_17
"firstName": "John",
_17
"lastName": "Doe",
_17
"email": "john.doe@example.com",
_17
"birthDate": "1925-11-17",
_17
"document": "12345678911",
_17
"documentType": "CPF"
_17
},
_17
"meta": {
_17
"version": "abc",
_17
"author": "e40e0b6d-0605-4fa6-8176-1d69fbaf0818",
_17
"creationDate": "13/12/2021T00:00:00Z",
_17
"lastUpdate": "13/12/2021T00:00:00Z"
_17
}
_17
}

Addresses

Addresses are linked to profiles and any profile can have as many addresses as it might need. This means that a valid profileId is necessary to perform any action regarding addresses.

Example request body for address creation

_11
{
_11
"postalCode": "20200-000",
_11
"countryName": "Brasil",
_11
"countryCode": "BR",
_11
"administrativeAreaLevel1": "RJ",
_11
"locality": "Locality",
_11
"localityAreaLevel1": "locality area",
_11
"route": "51",
_11
"streetNumber": "999",
_11
"profileId": "70caf394-8534-447e-a0ca-1803c669c771"
_11
}

Example response when getting unmasked address

_20
{
_20
"id": "bf82180e-cf9e-4089-9af6-ae1518555992",
_20
"document": {
_20
"postalCode": "20200-000",
_20
"countryName": "Brasil",
_20
"countryCode": "BR",
_20
"administrativeAreaLevel1": "RJ",
_20
"locality": "Locality",
_20
"localityAreaLevel1": "locality area",
_20
"route": "51",
_20
"streetNumber": "999",
_20
"profileId": "70caf394-8534-447e-a0ca-1803c669c771"
_20
},
_20
"meta": {
_20
"version": "c9c44895-4589-4d0d-a28d-e0e656ca1926",
_20
"author": "80aa79a3-aa89-4912-a20e-8ef69af19a6c",
_20
"creationDate": "2022-01-18T18:51:34.1293829+00:00",
_20
"lastUpdateDate": "2022-01-18T18:51:34.1293829+00:00"
_20
}
_20
}

Prospects

Purchase information

Schemas

A JSON Schema defines the structure of data stored in the Profile System. It determines, for example, which fields a profile has and their respective formats. Read Working with schemas in the Profile System for more information.

The following endpoints allow you to interact with the profile schema:

Contributors
2
Photo of the contributor
Photo of the contributor
+ 2 contributors
Was this helpful?
Yes
No
Suggest edits (Github)
See also
Data residency
Guides
Limitations of the PII data architecture during closed beta
Guides
Data Protection Plus
Guides
Changes in VTEX features behavior to handle PII data
Guides
PII Data Architecture specifications
Guides
Contributors
2
Photo of the contributor
Photo of the contributor
+ 2 contributors
On this page