Accelerate the Value of Data

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
ParameterTypeRequiredDescription
AuthorizationstringYesThe 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 stringYesThe 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
ParameterTypeRequiredDescription
tenantIdstringYesThe unique identification number for the Reltio tenant, for example:
AbCdEfGH12i3jK4
.
Table 3. Parameters - Query
ParameterTypeRequiredDescription
returnObjects boolean NoWhether the response contains updated entities: true (default) or false.
optionsarray(string) NoA 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 booleanNoWhether 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
ParameterTypeRequiredDescription
entities_to_updatearrayYesOne 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 CodeMessageDescription
200 Entities are successfully savedYou successfully created the requested entities.
400 Entities aren't saved due to a reason provided in the error messageCorrect 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.
401Unauthorized 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.
403The 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 returnedTypeDescription
Created entitiesarray
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"
	}
] 

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"
}]