home

Explore

DiscoverStartExploreModelIntegrateEngage
DiscoverStartExploreModelIntegrateEngage

Accelerate the Value of Data

Show Contents

thumbnailExplore

Update entities

Bulk update of attributes

Learn how to update the attributes for multiple entities in bulk.

This API initiates a bulk update task using which you can update attributes in bulk. The task divides the multiple updates into batches of 50 or fewer entities in the background.

Request 

POST {TenantURL}/entities/_update
Table 1. Parameters
Parameter Required Details
Headers Authorization Yes Information about authentication access token in format "Bearer <accessToken>" (see details in Authentication API).
Body Request definition Yes

The entities' list can be specified by using either a filter with an optional excludeList of entities, or, just a list of entities. Example 1 shows a filter and excludeList and Example 2 shows just a list of entities.

Example 1:

"objects": {
	"filter": "equals(attributes.Address.City, 'Las Vegas')
	and equals(type, 'configuration/entityTypes/HCP')
	",
	"excludeList": ["entities/AAA", "entities/BBB"]
	}

Example 2:

"objects": {
	"list": ["entities/AAA", "entities/BBB"]
}

Action contains an array of actions that will be applied to the selected entities.

Each action contains one of the following operation fields:
  • AddAttribute
  • UpdateAttribute
  • DeleteAttribute
  • RepointReferencedEntity
  • operationParameters

The AddAttribute operation adds a new attribute value to an entity. For every source type listed in the sourceTypes field, this value is a part of all winner crosswalks if the entity has crosswalks from the winner entity during a merge operation. All loser crosswalks are ignored. On the other hand, the value is a part of all loser crosswalks when the merged entity only has crosswalks from a loser entity. However, if there are no crosswalks for a listed source type, then a new crosswalk is created.

The UpdateAttribute operation updates the existing attribute values. This value is updated if all source types that it’s a part of are listed in the sourceTypes field. The attribute value’s Uniform Resource Identifier (URI) is also preserved. But a new value with its URI is added only if the value is a part of one or more crosswalks whose source types aren’t listed in the sourceTypes field, and is a part of all the crosswalks that are listed in the sourceTypes field. The URI of the earlier value is retained and is a part of all crosswalks that aren’t listed in the sourceTypes field. However, if the existing attribute value isn’t a part of one or more source types in the sourceTypes field, then the updated value is considered to be a part of an existing crosswalk or a new crosswalk (if there are no existing crosswalks) of these source types.

The DeleteAttribute operation affects all attribute values that pass the values in the valueFilter field and has corresponding attributeURI values. This operation deletes all values with crosswalk source types listed in the sourceTypes field, and ignores values that contain other crosswalks.

The RepointReferencedEntity operation changes the referenced entity for a reference attribute. For example, if you want to change the address reference for an entity.

The operationParameters operations can have any of the following fields:

  • sourceTypes (optional) - list of source types

  • attributeURI - target attribute type URI. Sub-attributes inside the reference attribute must be specified as entity attribute, rather than relation attribute (for example, configuration/entityTypes/HCP/attributes/Address/attributes/AddressRank)

  • addNestedAttributes - if true, it enables the user to add a parent to a nested attribute in a bulk update operation.

  • valueFilter (optional) - attribute value filter. Applied to attribute values and it’s possible to use the attribute value itself, nested attribute values, or, parent attribute value in the expression.

    • equals(value, 'Jakson')
    • equals(attributes.nestedAttribute, 'Jakson')
    • equals(parent.attributes.siblingAttribute, 'Jakson')

    • equals(referenced_entity_id, 'Location.1')- you can filter referenced attributes by the referenced entity.

  • attributeValue - new attribute value. Text value for simple attributes or JSON structure for a nested attribute. When adding a new reference attribute, the user can either specify a new referenced entity or an existing referenced entity URI in the objectURI field inside the refEntity node.

  • pin (optional) - specifies whether attribute value must be pinned

  • ignore (optional) - specifies whether attribute value must be ignored.

  • referencedEntity (optional) - specifies new end entity when re-pointing reference attribute. This can contain either a new entity or just a URI field to reference an existing entity.

Examples

Add an attribute

Request

POST {{api_uri}}/{{tenant}}/entities/_update
{
    "objects": {
        "list": [
            "entities/1uZzblK"
        ]
    },
    "actions": [
        {
            "operationParameters": {
                "sourceTypes": [
                    "HMS"
                ],
                "attributeURI": "configuration/entityTypes/HCP/attributes/MiddleName",
                "attributeValue": "MiddleName002"
            },
            "operation": "AddAttribute"
        }
    ]
}

Response

GET {{api_uri}}/{{tenant}}/entities/{{id}}
{
    "uri": "entities/1vERAkZ",
    "type": "configuration/entityTypes/HCP",
    "createdBy": "tselezneva",
    "createdTime": 1628484749041,
    "updatedBy": "tselezneva",
    "updatedTime": 1628484971718,
    "attributes": {
        "FirstName": [
            {
                "type": "configuration/entityTypes/HCP/attributes/FirstName",
                "ov": true,
                "value": "Simon",
                "uri": "entities/1vERAkZ/attributes/FirstName/BDVEKGsZ"
            }
        ],
        "LastName": [
            {
                "type": "configuration/entityTypes/HCP/attributes/LastName",
                "ov": true,
                "value": "Mitchell",
                "uri": "entities/1vERAkZ/attributes/LastName/BDVEKL8p"
            }
        ],
        "NestedTest": [
            {
                "label": "Added Nested",
                "value": {
                    "TextField": [
                        {
                            "type": "configuration/entityTypes/HCP/attributes/NestedTest/attributes/TextField",
                            "ov": true,
                            "value": "Added Nested",
                            "uri": "entities/1vERAkZ/attributes/NestedTest/8c7CAJDA/TextField/8c7CANTQ"
                        }
                    ],
                    "Int": [
                        {
                            "type": "configuration/entityTypes/HCP/attributes/NestedTest/attributes/Int",
                            "ov": true,
                            "value": "1111",
                            "uri": "entities/1vERAkZ/attributes/NestedTest/8c7CAJDA/Int/8c7CARjg"
                        }
                    ]
                },
                "ov": true,
                "uri": "entities/1vERAkZ/attributes/NestedTest/8c7CAJDA"
            }
        ]
    },
    "isFavorite": false,
    "crosswalks": [
        {
            "uri": "entities/1vERAkZ/crosswalks/8c7CAAge",
            "type": "configuration/sources/HMS",
            "value": "1vERAkZ",
            "reltioLoadDate": "2021-08-09T04:56:11.718Z",
            "createDate": "2021-08-09T04:56:11.718Z",
            "updateDate": "2021-08-09T04:56:11.718Z",
            "attributes": [
                "entities/1vERAkZ/attributes/NestedTest/8c7CAJDA/Int/8c7CARjg",
                "entities/1vERAkZ/attributes/NestedTest/8c7CAJDA/TextField/8c7CANTQ",
                "entities/1vERAkZ/attributes/NestedTest/8c7CAJDA"
            ],
            "singleAttributeUpdateDates": {
                "entities/1vERAkZ/attributes/NestedTest/8c7CAJDA/Int/8c7CARjg": "2021-08-09T04:56:11.718Z",
                "entities/1vERAkZ/attributes/NestedTest/8c7CAJDA/TextField/8c7CANTQ": "2021-08-09T04:56:11.718Z",
                "entities/1vERAkZ/attributes/NestedTest/8c7CAJDA": "2021-08-09T04:56:11.718Z"
            }
        },
        {
            "uri": "entities/1vERAkZ/crosswalks/8c7CAEwu",
            "type": "configuration/sources/FB",
            "value": "1vERAkZ",
            "reltioLoadDate": "2021-08-09T04:56:11.718Z",
            "createDate": "2021-08-09T04:56:11.718Z",
            "updateDate": "2021-08-09T04:56:11.718Z",
            "attributes": [
                "entities/1vERAkZ/attributes/NestedTest/8c7CAJDA/Int/8c7CARjg",
                "entities/1vERAkZ/attributes/NestedTest/8c7CAJDA/TextField/8c7CANTQ",
                "entities/1vERAkZ/attributes/NestedTest/8c7CAJDA"
            ],
            "singleAttributeUpdateDates": {
                "entities/1vERAkZ/attributes/NestedTest/8c7CAJDA/Int/8c7CARjg": "2021-08-09T04:56:11.718Z",
                "entities/1vERAkZ/attributes/NestedTest/8c7CAJDA/TextField/8c7CANTQ": "2021-08-09T04:56:11.718Z",
                "entities/1vERAkZ/attributes/NestedTest/8c7CAJDA": "2021-08-09T04:56:11.718Z"
            }
        },
        {
            "uri": "entities/1vERAkZ/crosswalks/BDVEKPP5",
            "type": "configuration/sources/Reltio",
            "value": "1vERAkZ",
            "reltioLoadDate": "2021-08-09T04:52:29.041Z",
            "createDate": "2021-08-09T04:52:29.041Z",
            "updateDate": "2021-08-09T04:52:29.041Z",
            "attributes": [
                "entities/1vERAkZ/attributes/FirstName/BDVEKGsZ",
                "entities/1vERAkZ/attributes/LastName/BDVEKL8p"
            ],
            "singleAttributeUpdateDates": {}
        }
    ],
    "analyticsAttributes": {},
    "label": "Simon Mitchell,",
    "secondaryLabel": ""
}

Update an attribute

Request

POST {{api_uri}}/{{tenant}}/entities/_update
{
    "objects": {
        "list": [
            "entities/0AR19KV"
        ]
    },
    "actions": [
        {
            "operationParameters": {
                "attributeURI": "configuration/entityTypes/HCP/attributes/FirstName",
                "valueFilter": "equals(value, 'Saimon')",
                "attributeValue":  "Gregory"
            },
            "operation": "UpdateAttribute"
        }
    ]
}

Response

GET {{api_uri}}/{{tenant}}/entities/{{id}}
{
    "uri": "entities/0AR19KV",
    "type": "configuration/entityTypes/HCP",
    "createdBy": "tselezneva",
    "createdTime": 1628497257398,
    "updatedBy": "tselezneva",
    "updatedTime": 1628497365747,
    "attributes": {
        "FirstName": [
            {
                "type": "configuration/entityTypes/HCP/attributes/FirstName",
                "ov": true,
                "value": "Gregory",
                "uri": "entities/0AR19KV/attributes/FirstName/ykeRkah"
            },
            {
                "type": "configuration/entityTypes/HCP/attributes/FirstName",
                "ov": true,
                "value": "Simon",
                "uri": "entities/0AR19KV/attributes/FirstName/ykeRgKR"
            }
        ],
        "LastName": [
            {
                "type": "configuration/entityTypes/HCP/attributes/LastName",
                "ov": true,
                "value": "Mitchell",
                "uri": "entities/0AR19KV/attributes/LastName/ykeRoqx"
            }
        ]
    },
    "isFavorite": false,
    "crosswalks": [
        {
            "uri": "entities/0AR19KV/crosswalks/ykeRt7D",
            "type": "configuration/sources/Reltio",
            "value": "0AR19KV",
            "reltioLoadDate": "2021-08-09T08:20:57.398Z",
            "createDate": "2021-08-09T08:20:57.398Z",
            "updateDate": "2021-08-09T08:20:57.398Z",
            "attributes": [
                "entities/0AR19KV/attributes/FirstName/ykeRgKR",
                "entities/0AR19KV/attributes/LastName/ykeRoqx",
                "entities/0AR19KV/attributes/FirstName/ykeRkah"
            ],
            "singleAttributeUpdateDates": {}
        }
    ],
    "analyticsAttributes": {},
    "label": "Gregory Mitchell,",
    "secondaryLabel": ""
}

Delete an attribute

Request

POST {{api_uri}}/{{tenant}}/entities/_update
{
    "objects": {
        "list": [
            "entities/0AR2nch"
        ]
    },
    "actions": [
        {
            "operationParameters": {
                "attributeURI": "configuration/entityTypes/HCP/attributes/FirstName",
                "valueFilter": "equals(value, 'Saimon')"
            },
            "operation": "DeleteAttribute"
        }
    ]
}

Response

GET {{api_uri}}/{{tenant}}/entities/{{id}}
{
    "uri": "entities/0AR2nch",
    "type": "configuration/entityTypes/HCP",
    "createdBy": "tselezneva",
    "createdTime": 1628508396543,
    "updatedBy": "tselezneva",
    "updatedTime": 1628508489430,
    "attributes": {
        "FirstName": [
            {
                "type": "configuration/entityTypes/HCP/attributes/FirstName",
                "ov": true,
                "value": "Simon",
                "uri": "entities/0AR2nch/attributes/FirstName/ykepKXD"
            }
        ],
        "LastName": [
            {
                "type": "configuration/entityTypes/HCP/attributes/LastName",
                "ov": true,
                "value": "Mitchell",
                "uri": "entities/0AR2nch/attributes/LastName/ykepT3j"
            }
        ]
    },
    "isFavorite": false,
    "crosswalks": [
        {
            "uri": "entities/0AR2nch/crosswalks/ykepXJz",
            "type": "configuration/sources/Reltio",
            "value": "0AR2nch",
            "reltioLoadDate": "2021-08-09T11:26:36.543Z",
            "createDate": "2021-08-09T11:26:36.543Z",
            "updateDate": "2021-08-09T11:26:36.543Z",
            "attributes": [
                "entities/0AR2nch/attributes/FirstName/ykepKXD",
                "entities/0AR2nch/attributes/LastName/ykepT3j"
            ],
            "singleAttributeUpdateDates": {}
        }
    ],
    "analyticsAttributes": {},
    "label": "Simon Mitchell,",
    "secondaryLabel": ""
}

Repoint a reference entity for an attribute

Request

POST {{api_uri}}/{{tenant}}/entities/_update
{
    "objects": {
        "list": [
            "entities/1Xd78XT"
        ]
    },
    "actions": [
        {
            "operationParameters": {
                "attributeURI": "configuration/entityTypes/HCP/attributes/Address",
                "valueFilter": "equals(referenced_entity_id,'1Xd7H3z')",
                "referencedEntity": {
                    "uri": "entities/0yxtctf"
                }
            },
            "operation": "RepointReferencedEntity"
        }
    ]
}

Response

GET {{api_uri}}/{{tenant}}/entities/{{id}}
{
    "uri": "entities/1Xd78XT",
    "type": "configuration/entityTypes/HCP",
    "createdBy": "tselezneva",
    "createdTime": 1628531133613,
    "updatedBy": "tselezneva",
    "updatedTime": 1628531552500,
    "attributes": {
        "FirstName": [
            {
                "type": "configuration/entityTypes/HCP/attributes/FirstName",
                "ov": true,
                "value": "Simon",
                "uri": "entities/1Xd78XT/attributes/FirstName/A3HMJYdn"
            }
        ],
        "LastName": [
            {
                "type": "configuration/entityTypes/HCP/attributes/LastName",
                "ov": true,
                "value": "Mitchell",
                "uri": "entities/1Xd78XT/attributes/LastName/A3HMJcu3"
            }
        ],
        "Address": [
            {
                "label": "Address_1",
                "relationshipLabel": "Home",
                "value": {
                    "AddressType": [
                        {
                            "type": "configuration/relationTypes/HasAddress/attributes/AddressType",
                            "ov": true,
                            "value": "Home",
                            "lookupError": "Lookup isn't found",
                            "uri": "entities/1Xd78XT/attributes/Address/1IyYX5f/AddressType/A3HMJyDL"
                        }
                    ],
                    "AddressLine1": [
                        {
                            "type": "configuration/entityTypes/Location/attributes/AddressLine1",
                            "ov": true,
                            "value": "Address_1",
                            "uri": "entities/1Xd78XT/attributes/Address/1IyYX5f/AddressLine1/5yeo16WR"
                        }
                    ]
                },
                "ov": true,
                "uri": "entities/1Xd78XT/attributes/Address/1IyYX5f",
                "refEntity": {
                    "type": "configuration/entityTypes/Location",
                    "crosswalks": [
                        {
                            "uri": "entities/1Xd78XT/crosswalks/0yxtctf.5yeo1Amh",
                            "type": "configuration/sources/FB",
                            "value": "loc_1",
                            "createDate": "2021-08-09T17:44:04.476Z",
                            "updateDate": "2021-08-09T17:44:04.476Z",
                            "attributeURIs": [
                                "entities/1Xd78XT/attributes/Address/1IyYX5f/AddressLine1/5yeo16WR",
                                "entities/1Xd78XT/attributes/Address/1IyYX5f"
                            ]
                        },
                        {
                            "uri": "entities/1Xd78XT/crosswalks/0yxtctf.5yeqVRDn",
                            "type": "configuration/sources/Reltio",
                            "value": "0yxtctf",
                            "createDate": "2021-08-09T17:52:32.500Z",
                            "updateDate": "2021-08-09T17:52:32.500Z"
                        }
                    ],
                    "objectURI": "entities/0yxtctf"
                },
                "refRelation": {
                    "type": "configuration/relationTypes/HasAddress",
                    "crosswalks": [
                        {
                            "uri": "entities/1Xd78XT/crosswalks/1IyYX5f.A3HMKepv",
                            "type": "configuration/sources/Reltio",
                            "value": "1IyYX5f",
                            "createDate": "2021-08-09T17:45:33.613Z",
                            "updateDate": "2021-08-09T17:45:33.613Z",
                            "attributeURIs": [
                                "entities/1Xd78XT/attributes/Address/1IyYX5f",
                                "entities/1Xd78XT/attributes/Address/1IyYX5f/AddressType/A3HMJyDL"
                            ]
                        }
                    ],
                    "startRefPinned": false,
                    "endRefPinned": false,
                    "startRefIgnored": false,
                    "endRefIgnored": false,
                    "objectURI": "relations/1IyYX5f"
                },
                "startObjectCrosswalks": [
                    {
                        "type": "configuration/sources/Reltio",
                        "value": "1Xd78XT"
                    }
                ],
                "endObjectCrosswalks": [
                    {
                        "type": "configuration/sources/Reltio",
                        "value": "0yxtctf"
                    }
                ]
            },
            {
                "label": "350 Hawthorne Ave",
                "relationshipLabel": "ShipTo",
                "value": {
                    "AddressType": [
                        {
                            "type": "configuration/relationTypes/HasAddress/attributes/AddressType",
                            "ov": true,
                            "value": "ShipTo",
                            "lookupError": "Lookup isn't found",
                            "uri": "entities/1Xd78XT/attributes/Address/1IyYSpP/AddressType/A3HMJlQZ"
                        }
                    ],
                    "AddressLine1": [
                        {
                            "type": "configuration/entityTypes/Location/attributes/AddressLine1",
                            "ov": true,
                            "value": "350 Hawthorne Ave",
                            "uri": "entities/1Xd78XT/attributes/Address/1IyYSpP/AddressLine1/A3HMJpgp"
                        }
                    ]
                },
                "ov": true,
                "uri": "entities/1Xd78XT/attributes/Address/1IyYSpP",
                "refEntity": {
                    "type": "configuration/entityTypes/Location",
                    "crosswalks": [
                        {
                            "uri": "entities/1Xd78XT/crosswalks/1Xd7Cnj.A3HMKS39",
                            "type": "configuration/sources/Reltio",
                            "value": "1Xd7Cnj",
                            "createDate": "2021-08-09T17:45:33.613Z",
                            "updateDate": "2021-08-09T17:45:33.613Z",
                            "attributeURIs": [
                                "entities/1Xd78XT/attributes/Address/1IyYSpP/AddressLine1/A3HMJpgp",
                                "entities/1Xd78XT/attributes/Address/1IyYSpP"
                            ]
                        }
                    ],
                    "objectURI": "entities/1Xd7Cnj"
                },
                "refRelation": {
                    "type": "configuration/relationTypes/HasAddress",
                    "crosswalks": [
                        {
                            "uri": "entities/1Xd78XT/crosswalks/1IyYSpP.A3HMKWJP",
                            "type": "configuration/sources/Reltio",
                            "value": "1IyYSpP",
                            "createDate": "2021-08-09T17:45:33.613Z",
                            "updateDate": "2021-08-09T17:45:33.613Z",
                            "attributeURIs": [
                                "entities/1Xd78XT/attributes/Address/1IyYSpP/AddressType/A3HMJlQZ",
                                "entities/1Xd78XT/attributes/Address/1IyYSpP"
                            ]
                        }
                    ],
                    "startRefPinned": false,
                    "endRefPinned": false,
                    "startRefIgnored": false,
                    "endRefIgnored": false,
                    "objectURI": "relations/1IyYSpP"
                },
                "startObjectCrosswalks": [
                    {
                        "type": "configuration/sources/Reltio",
                        "value": "1Xd78XT"
                    }
                ]
            }
        ]
    },
    "isFavorite": false,
    "crosswalks": [
        {
            "uri": "entities/1Xd78XT/crosswalks/A3HMKj6B",
            "type": "configuration/sources/Reltio",
            "value": "1Xd78XT",
            "reltioLoadDate": "2021-08-09T17:45:33.613Z",
            "createDate": "2021-08-09T17:45:33.613Z",
            "updateDate": "2021-08-09T17:45:33.613Z",
            "attributes": [
                "entities/1Xd78XT/attributes/FirstName/A3HMJYdn",
                "entities/1Xd78XT/attributes/LastName/A3HMJcu3"
            ],
            "singleAttributeUpdateDates": {}
        }
    ],
    "analyticsAttributes": {},
    "label": "Simon Mitchell,",
    "secondaryLabel": "Address_1"
}

Updating Tags

The tags associated with multiple entities can be managed as a bulk update. The following operations are available for working with tags:
  • AddTags - To add one or more new tags
  • ReplaceTag - To replace an existing tag with another tag
  • DeleteTags - To delete the existing tags by specifying the tags to be deleted
  • ClearTags - To clear all the existing tags without specifying the tags in the request
Request Sample for Tags: 
{
    "actions": [
        {
            "operation": "AddTags",
            "operationParameters": {
                "tags": [ "a", "b", "c" ]
            }
        },
        {
            "operation": "ReplaceTag",
            "operationParameters": {
                "newValue": "c",
                "oldValue": "d"
            }
        },
        {
            "operation": "DeleteTags",
            "operationParameters": {
                "tags": [ "a", "b" ]
            }
        },
        {
            "operation": "ClearTags"
        }
    ],
    "objects": {
        "list": [ "entities/a", "entities/b" ]
    }
}

Response

JSON object with created Bulk Attribute Update task information.

Request 

POST {
	TenantURL
}
/entities/_update
Headers: Authorization: Bearer c3f28fdd-e082-4 f90-8840-9896914e af41 {
	"objects": {
		"filter": "equals(attributes.Address.City, 'Las Vegas') and equals(type, 'configuration/entityTypes/HCP')",
		"excludeList": ["entities/AAA", "entities/BBB"]
	},
	"actions": [{
		"operation": "AddAttribute",
		"operationParameters": {
			"sourceTypes": ["FB", "Reltio"],
			"attributeURI": "configuration/entityTypes/HCP/attributes/FirstName",
			"attributeValue": "John"
		}
	}]
}

Response 

{
	"id": "35e465b1-f7c5-462d-a78e-ba9158c0e6c7",
	"createdTime": 1447237852497,
	"createdBy": "username",
	"updatedTime": 1447237852497,
	"updatedBy": "username",
	"type": "com.reltio.businesslogic.tasks.update.UpdateAttributesTask",
	"status": "SCHEDULED",
	"createdOnHost": "tst-01-asdl04",
	"parallelExecution": false,
	"parameters": {
		"tenantId": "tenantName",
		"updateAttributesRequest": "..."
	},
	"currentState": {},
	"duration": "0s"
}

Updated on March 29, 2024

Footer

You've found your way to a temporary environment. Content is not complete or final. Looking for Reltio documentation? Go to docs.reltio.com.

Company

Leadership

Careers

Awards

Contact Us

Reltio Newsroom

Press Releases

Media Coverage

Media & Analyst Resources

Customer Support

Support

Reltio Learn

Community

Developer Portal

100 Marine Parkway, Suite 275

Redwood Shores, CA 94065

USA

North America: +1(855)360-3282

Europe: +44(800)368-7643

Email: sales@reltio.com

© 2022-2024 Reltio Intellectual Property. All rights reserved.

Terms, Policies & Cookie Preferences