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

Check the changes in VTEX features behavior to handle PII data that impact other integrations.
Check the current limitations related to PII data architecture. Note that, at the moment, Master Data triggers are not supported by the PII platform version Profile System, for example.

Permission

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

Product	Category	Resource	Description
Profile System	Documents	Get Item	Get items in Profile System entities
Profile System	Documents	Save and Update Item	Edit items from Profile System.
Profile System	Documents	Delete Item	Delete 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.

Learn more about how to audit actions in the VTEX platform.

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

Action	Description	Event details
GetProfileVersionUnmasked	Retrieval of an unmasked profile by ID and version.	Profile ID and version ID.
EmailRectification	Change 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:

Parameter	Required	Type	Description
`reason`	Yes	String	Reason 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: