Skip to content
Optima docs
Concepts

Profiles and entities

What a profile is, how entity types describe profiles, and how profiles are created, read, linked and merged.

A profile is Optima's record of one subject: a customer, a household, a device, an account, a product. Everything else in Optima, from events to segments to consent, hangs off profiles.

What a profile holds

Every profile has a permanent identifier assigned by Optima, an entity type (what kind of subject it is) and a creation time. Three kinds of information sit on it:

  • Identifiers are business keys such as email, phone or loyalty_id. A profile can have many. Identifiers are how incoming data finds the right profile: when you send data with an email address that Optima already knows, it updates that profile rather than creating a new one.
  • Attributes are the descriptive fields: first name, city, lifetime value, date of birth. Each has a type. See attributes and computed attributes.
  • Links are relationships to other profiles, such as a customer who belongs to a household.

Entity types: the schema

An entity type defines one kind of profile. You manage entity types in the console under Settings → Workspace → Schema, on the Entities tab. An entity type has:

PartMeaning
NameThe entity type's unique name, for example customer.
Parent entityOptional. Models a hierarchy, for example a device that belongs to a customer.
DescriptionFree text for your colleagues.
AttributesThe attributes profiles of this type can have, each with a type, a PII level and optional consent purposes.
IdentifiersThe identifier keys profiles of this type can have, each with a PII level.
StrictWhen on, data carrying an attribute the entity type does not declare is rejected. When off (the default), unknown attributes are accepted.

Event types are defined next to entity types, on the Event types tab. See events.

Defining the schema is optional but recommended. It makes values consistent, it lets Optima reject malformed data early in strict mode, and it is how personal fields are labelled for privacy. The PII level on an attribute decides who may see it, and the purposes on an attribute say which reasons for processing allow it. See consent and purposes.

Creating and updating profiles

Optima writes profiles as an upsert with partial-update behaviour. You supply identifiers and the attributes you know. Optima finds the profile that matches, or creates one, and merges your attributes in. Attributes you do not mention keep their stored values. An identifier you send that no profile has yet, such as a newly learned email address, is added to the matched profile. If the identifiers you send already belong to two different profiles, the API stores nothing and answers 409 with the reason identifier_conflict, listing which identifier keys belong together. Merge the two profiles first, or send only one profile's identifiers. Connector imports instead update the first matching profile, unless the connector has Reject rows matching multiple profiles turned on. The result reports whether the profile was created or updated.

In the console you create a profile with Add profile on the Profiles screen and edit attributes from a profile's page. Integrations and the SDKs normally do this for you. In the API it is the profile set operation; see the API reference.

Every write is checked against the schema and any data contract that applies. A data contract states which attributes must be present and how they must look. When a contract requires an attribute, a profile that already has that attribute stored satisfies it.

After a write, Optima re-checks it for identity matches shortly afterwards and refreshes signals that depend on the changed attributes. These follow-up steps happen in the background and never make the write fail.

Reading profiles

On the Profiles screen you find profiles by identifier, or with the advanced filter. A profile's page has tabs: Overview, Signals & Cohorts, Identity & Links, Consent & Privacy and History.

What you see depends on privacy rules. Each attribute is shown or hidden according to your acting purpose, your PII access level and the customer's consent. The profile page tells you how many attributes are hidden and why, and offers Change purpose if choosing another acting purpose is the fix. Every read of personal data is written to the audit log. See consent and purposes.

Reading the past

Optima keeps a history of every change. The History tab on a profile shows it, and the API can return a profile as it was at a past moment: give the read operation an at timestamp. If the profile did not exist yet, or had already been deleted, at that moment, the answer is not found. The same privacy filtering applies to historical data as to current data.

A link is a directed relationship from a parent profile to a child profile, with a relation type such as household-customer. Links created by identity resolution use the relation type identity and also record a confidence. You can add, edit and remove links on the Identity & Links tab.

The two profiles in a link cannot be changed. To connect different profiles, remove the link and create a new one. Removing a link between a pair removes all relation types between them unless you name one.

Links matter beyond display. Segments can ask about related profiles, and a fatigue policy can cap contact across a whole linked hierarchy such as a household.

Merging profiles

Merge folds a source profile into a target profile of the same entity type. The source's events, identifiers and attributes move to the target, and the source profile is removed. The target keeps a record of the profile it absorbed, so you can trace where data came from.

When both profiles have a value for the same attribute, the newer value wins. Merging a profile with itself, merging a pair that is already merged, and merging different entity types are all refused.

Merging is permanent in practice, because the absorbed profile is gone. If you are not sure two profiles are one person, prefer identity resolution, which leaves the originals untouched.

Deleting profiles

Removing a profile deletes it as an operational action. It is not the right tool for a customer's request to be forgotten: that is the auditable erasure process, covered in consent and purposes.

On this page