Update entities

Learn about the Entities API to update one or more entities in your Reltio tenant.

Use the Entities to update one or more existing entities in your Reltio tenant.

A Reltio entity describes a data object such as a person, organization, product, or location. Entities are comprised of properties such as URIs, type, labels, roles, tags, attributes, crosswalks, and timestamps. For more information, see topic Reltio entity types.

You need to have a role with the appropriate access permissions (rights and privileges) to run this API:

ROLE_ADMIN_CUSTOMER
ROLE_ADMIN_TENANT
ROLE_ADMIN_USER
ROLE_API
ROLE_USER

This topic describes how to use the Entities to update entities. For more information on the syntax of this API, see the Reltio Development Portal. For more specific usage scenarios for this API, see the sub topics in this section.

You use the same API to create entities, but with different parameters. For more information, see topic Create entities.

Request

POST /services/reltio/api/{tenantId}/entities/

Table 1. Header
Parameter	Type	Required	Description
Authorization	string	Yes	The bearer token URL returned by the Authentication.For information on obtaining an authorization token to run Reltio REST APIs using the Security OAuth 2.0 security method, see topic Authentication API.
Content-type	string	Yes	The format to use to transmit data: application/json Reltio APIs transmit data in the JavaScript Object Notation (JSON) standard text-based format.

Table 2. Parameters - Path
Parameter	Type	Required	Description
tenantId	string	Yes	The unique identification number for the Reltio tenant, for example: `AbCdEfGH12i3jK4` .

Table 3. Parameters - Query
Parameter	Type	Required	Description
returnObjects	boolean	No	Whether the response contains updated entities: true (default) or false.
options	array(string)	No	A comma-separated list of options that determines the contents of the response the API endpoint returns: ovOnly: Return only attribute values that have `ov=true` flag. nonOvOnly: Return only attribute values that have `ov=false` flag. If a nested or reference attribute value has `ov=true` while its sub attributes have `ov=false`, then these sub attributes are not returned in the response. `partialOverride` Whether to overwrite an existing entity with the attributes specified in the update request: true or false (default). No other attributes are affected. preserveHidden: Whether to create a data change request (DCR) to delete hidden attributes if they are not specified in the request. preserveURIs: Include in the respone URIs for an entity or attribute values specified in the update request. sendHidden: Whether to return hidden attributes in the response: true or false (default). updateAttributeUpdateDates: Whether to overwrite the date in the crosswalks singleAttributeUpdateDates property for updated attributes when a match with an existing entity is found: true or false (default). For more information on the effect of update date parameters on a crosswalk's `updateDate` property, see topic Retrieve or modify an entity crosswalk updateDate.
executeLCA	boolean	No	Whether to trigger the specified Lifecycle Actions during this request: true (default) or false. For more information, see topic LCA Framework. Note: During dataload, for an asynchronous incremental match thread, the LCA is called regardless of the setting of this `executeLCA`

Table 4. Parameters - Body
Parameter	Type	Required	Description
entities_to_update	array	Yes	One or more Reltio entity objects to be updated. Note: If you don't specify roles in this update request, then all roles from the entity being overwritten will remain unchanged. If you want to remove all roles from the existing entity, then you must specify an empty array of Roles in this update request.

Response

The API endpoint returns a response in JSON format. The response contents depend on the parameters you passed in the request.

Table 5. Status code
Status Code	Message	Description
200	`Entities are successfully saved`	You successfully created the requested entities.
400	`Entities aren't saved due to a reason provided in the error message`	Correct the issues identified in the error code. For example, if you receive this error message: { "severity": "Error", "errorMessage": "Failed to parse content as JSON", "errorCode": 150, "errorDetailMessage": "Expecting request content in JSON format, failed to parse. Reason: Code: ... } } Ensure that your uploaded file is in JSON format and that you specify Content-type correctly when you retry your POST request.
401	`Unauthorized`	Correct the issues identified in the error code. For example, if you receive this error message: { "error": "invalid_token", "error_description": "Token is invalid: 1a2b3c45-6def-7hi8-j901-k23456789l01" } Ensure you entered your authorization token correctly, refresh the token, or obtain a new authorization token when you retry your POST request.
403	`The operation is forbidden for the current user, please check your privileges`	Correct the issues identified in the error code. For example, if you receive this error message: { "severity": "Error", "errorMessage": "Security error. This endpoint is forbidden for current user.", "errorCode": 804, "errorDetailMessage": "Security error. This endpoint is forbidden for current user.", ... } } Ensure that any specified users have the necessary roles when you retry your POST request.

Table 6. Response body
Data returned	Type	Description
Created entities	array	Results for each entity updated by the request: `index` (required): An index of an entity object in the JSON array of entities that was updated. `object` (if the `returnObjects` query parameter in the request wasn't set to false): Complete details of the entity object created: uri type tags createdBy createdTime updatedBy updatedTime isFavorite analyticsAttributes label secondaryLabel crosswalks attributes . Note: By default, hidden attributes aren't returned unless you set the `options=ov` parameter to false in the request. `successful`: Whether the request for this entity is successful: `true`: Successful `false`: Not successful. In this case, when the entity can't be created, the response contains details of the issue: `errors`: `warning`: The object was created, but there were some problems. `status`: The result of operation; possible values are `OK` or `failed`.

Examples

This request updates the value of the second entity from "John" to "Johhny".

Table 7. Request example
`POST { TenantURL } /entitiesHeaders: Authorization: Bearer 204938 ca-2 cf7-44 b0-b11a-1 b4c59984512, Content-Type: application / jsonBody: [{ "type": "configuration/entityTypes/Individual", "tags": ["sport", "movies"] }, { "roles": ["configuration/roles/Client", "configuration/roles/Prospect"], "attributes": { "FirstName": [{ "value": "Ivan" }, { "type": "configuration/entityTypes/Individual/attributes/FirstName", "value": "Johnny" }] } }, { "type": "configuration/entityTypes/Organization" } ]`

POST {
	TenantURL
}
/entitiesHeaders: Authorization: Bearer
204938 ca-2 cf7-44 b0-b11a-1 b4c59984512, Content-Type: application / jsonBody: [{
		"type": "configuration/entityTypes/Individual",
		"tags": ["sport", "movies"]
	}, {
		"roles": ["configuration/roles/Client", "configuration/roles/Prospect"],
		"attributes": {
			"FirstName": [{
				"value": "Ivan"
			}, {
				"type": "configuration/entityTypes/Individual/attributes/FirstName",
				"value": "Johnny"
			}]
		}
	},
	{
		"type": "configuration/entityTypes/Organization"
	}
]

This example shows the response the API returns for the update request example above.

Table 8. Response example
POST { TenantURL } /entitiesHeaders: Authorization: Bearer 204938 ca-2 cf7-44 b0-b11a-1 b4c59984512, Content-Type: application / json Body: [{ "index": 0, "URI": "entities/10", "object": { "URI": "entities/10", "type": "configuration/entityTypes/Individual", "tags": ["sport", "movies"] }, "status": "OK" }, { "index": 1, "error": {.. "type property is required".. }, "status": "failed" }, { "index": 3, "URI": "entities/11", "object": { "URI": "entities/11", "type": "configuration/entityTypes/Organization" }, "warning": { "code": 20001, "message": "Created entity has no attributes" }, "status": "OK" }]

POST {
	TenantURL
}
/entitiesHeaders: Authorization: Bearer
204938 ca-2 cf7-44 b0-b11a-1 b4c59984512, Content-Type: application / json Body: [{
	"index": 0,
	"URI": "entities/10",
	"object": {
		"URI": "entities/10",
		"type": "configuration/entityTypes/Individual",
		"tags": ["sport", "movies"]
	},
	"status": "OK"
}, {
	"index": 1,
	"error": {..
		"type property is required"..
	},
	"status": "failed"
}, {
	"index": 3,
	"URI": "entities/11",
	"object": {
		"URI": "entities/11",
		"type": "configuration/entityTypes/Organization"
	},
	"warning": {
		"code": 20001,
		"message": "Created entity has no attributes"
	},
	"status": "OK"
}]

Unify and manage your data

Update entities

Request

Response

Examples

Footer