- Introduction
- Pin attribute in Reltio context
- Difference between Survivorship and Pin attribute in Reltio
- Pin attribute – usage
- Conclusion
- Resources
Introduction
In Reltio, the same attribute often has multiple values coming from different sources. The “leading” value is automatically selected based on survivorship rules (ov = true). When the business requires a specific value to remain as the leading one regardless of calculations, a pin marker is used to lock the selection.
Pin attribute in Reltio context
In Reltio, a pin is a property applied to a specific attribute value that locks it as the operational value (OV), regardless of the results determined by survivorship logic. This means the system will continue to use that particular value during processing and integrations until the pin flag is manually removed or the value itself is modified. Essentially, the pin temporarily overrides the automatic selection mechanism and forces the system to prioritize a defined value.
This functionality is particularly important when the value has been verified by a business user, validated through a regulatory process, or is part of a workflow where any automatic change could lead to inconsistencies or issues in connected downstream systems.
Difference between Survivorship and Pin attribute in Reltio
In Reltio, survivorship is a dynamic process that automatically determines the most reliable value for a given attribute based on predefined, objective criteria – such as source quality, update date, frequency, and other similar factors. The result of this process is the operational value (OV), which can change whenever new or updated data is received.
In contrast, a pin is a deliberate, subjective intervention in this process. It reflects a business decision that essentially says: “I know the automatic rules would select another value, but I want this specific one to remain active.” Applying a pin locks the selection and temporarily disables the effect of survivorship logic. As long as the pin flag is active, the system will not change the OV automatically, regardless of any new incoming data. Once the pin is removed (pin = false), the survivorship mechanism is reactivated and determines a new OV.
Pin attribute – usage
The pin attribute can be applied either through the user interface (UI) or by sending an API request -for example, using Postman. Since this is not the main focus of the article, you can refer to the Pin attribute documentation for details on the type of request needed to apply a pin via Postman.
In the examples below, the Reltio UI is used to demonstrate how to apply a pin attribute to a specific value within a profile.
Case 1 – applying the pin attribute to simple attributes
Simple attributes in Reltio are flat – they do not contain nested structures or sub-attributes. Typical examples include FirstName, Gender, TaxID, and others.
When a pin attribute is applied to a simple attribute, Reltio locks the specific value as the Operational Value (OV). Even if new values arrive from external sources, the system will retain the current OV as long as the pin is active.
Because simple attributes have no internal structure, the pin flag remains stable and cannot be “lost” indirectly through metadata changes or structural updates.
In the current example, the profile has FirstName = John, which is pinned.
Even if another source which is higher in the hierarchy sends a new value, such as “Jane,” Reltio will keep John as the active value. This is because the pin takes precedence over survivorship logic.
When another system contributes the same value that already has a pin applied, the flag will automatically be transferred to the newly received value from the new source.
In the example above, if a new system sends the value John for the FirstName attribute, and that value is already pinned, Reltio will automatically apply the pin to the newly contributed value as well.
Case 2 – applying the pin attribute to nested attributes
The system behaves differently when the pin attribute is applied to a nested attribute. Unlike simple attributes, nested attributes have a multi-level structure and contain sub-attributes. Common examples include Email, Addresses, Phone, and others.
When a pin is applied at the container level (i.e. to the entire object), Reltio locks that specific nested object as OV. However, issues arise when new values are received from external sources. Even if only a single sub-field is updated, Reltio treats the entire object as a new instance and change the uri of the updated sub-attribute. As a result, the previous instance is removed from the active values, and with it, the pin flag is also lost.
This behavior often leads to confusion – especially among users who apply a pin directly to a container attribute, without realizing that partial updates may unintentionally overwrite the pinned value.
This scenario is illustrated in the example below, where a pin is applied to the entire Email container.
After an update is received – only for one field, in this case EmailLastUpdatedDate – Reltio treats the object as a new record. The old instance is removed from the active view, and the pin flag is lost as a result.
Avoiding pin attribute loss on nested attributes
To prevent the loss of the pin attribute when working with nested attributes in Reltio, several changes must be applied both in the configurations and in the way requests are sent to the platform.
Steps
- Update the Physical (Tenant) configuration
Because the issue affects the pin attribute functionality for nested attributes, the first step is to enable the nestedPartialOverride field in the Tenant configuration.
For PROD environments, this usually requires opening a ticket with Reltio Support so they can enable it – EnableNestedPartialOverride
- Update the L3 configuration
For every nested attribute, you need to add the keyAttributeURIs property. This property defines which values Reltio uses to match objects such as Emails, Phones, or Addresses.
This ensures that when an update is sent for the same email but with a different EmailLastUpdateDate, Reltio will recognize it as the same object.
It is a good practice to include fields that always have the same value in the request.
For example, if the email value is different, Reltio will treat it as a new object, and this is not related to the pin attribute.
keyAttributeURIs must be added in the entityTypes section for the specific entity type and for the specific attribute that requires it.
- Example for Email
"keyAttributeURIs": [ "configuration/entityTypes/[entityType]/attributes/Email/attributes/Email" ],
- Example for Phone
"keyAttributeURIs": [ "configuration/entityTypes/[entityType]/attributes/Phone/attributes/Number" ],
- Example for Address
"keyAttributeURIs": [ "configuration/entityTypes/Individual/attributes/Addresses/attributes/AddressLine1", "configuration/entityTypes/Individual/attributes/Addresses/attributes/City", "configuration/entityTypes/Individual/attributes/Addresses/attributes/StateProvince", "configuration/entityTypes/Individual/attributes/Addresses/attributes/Zip5" ],
More information about keyAttributeURIs is available here – KeyAttributesURI.
- Add partialOverride to the request sent to Reltio
Each request sent to Reltio must include the following parameter
options = partialOverride
This ensures that Reltio performs a partial update of the nested structure instead of overwriting it completely.
Result
By applying these three steps, any update made to a subfield inside a nested structure will keep the pin attribute at the container level. This can be seen in the example below.
- The existing Reltio record contains an Email with a pin value
- After receiving an update for EmailLastUpdateDate, the pin value on the container remains the same, and the date is successfully updated
The provided solution fixes the issue with overriding a pinned attribute inside nested attributes. Keep in mind that partialOverride updates only the information that is included in the request.
Important clarification
This means that if a profile in Reltio has Email, Address, and Phone, and after an update the profile should no longer have an Address, but the Address data is not included in the request, then the Address information will remain in Reltio. The reason is that partialOverride changes only the attributes that are explicitly sent.
This behavior can lead to a mismatch between the data a system contributes and the data stored in Reltio. However, this is expected and is part of the design of partialOverride.
Conclusion
Using the pin attribute correctly in Reltio is important for maintaining data consistency across updates and integrations – especially when business rules require certain values to remain fixed. While pinning simple attributes is generally straightforward and stable, working with nested attributes demands a more careful and targeted approach.
To prevent unexpected behavior and data loss, the steps described above must be followed when applying a pin to container attributes. This ensures that no information or pin value is lost.
