Create entities

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

Use the Entities to create one or more 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

You use the same API to update entities, but with different parameters. For more information, see topic Update 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 created 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 the `ov=true` flag. `nonOvOnly`: return only attribute values that have the `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. `preserveHidden`: Whether to create a data change request (DCR) to delete hidden attributes if they are not specified in the request. preserveURIs: Whether to include in the respone URIs for an entity or attribute values specified in the request. sendHidden: Whether to return hidden attributes in the response: true or false (default).
executeLCA	boolean	No	Whether to trigger all 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` parameter.

Table 4. Parameters - Body
Parameter	Type	Required	Description
entities_to_create	array	Yes	One or more Reltio entity objects to be created. To create a single entity, specify just one JSON object in this array. Each entity object requires the `type` property. The `URI` and `crosswalks` properties are optional. If you include crosswalks in the request (for example, `crosswalk1` and `crosswalk2`), and they correspond to some existing entities (`entity1` and `entity2`) in the tenant, then the API merges these entities into one survivor entity (for example, `entity1` is merged into `entity2`). After this occurs, the resultant survivor entity, `entity2`, is updated with the new information from a posted entity. Otherwise, if no entities are found or provided in the posted entity crosswalks, or no crosswalks are provided, then a new entity is created.

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. You can send an array of entities in one request. The status code is 200 even if all entities are not successfully created. The response payload contains the details of the error in creating failed entities. For example, you send five entities to update and only one contains an error in response. The response contains the following error: [ { "index": 0, "errors": { "severity": "Error", "errorMessage": "Type is not found for URI configuration/entityTypes/HCP45 and tenant LocalTenantId", "errorCode": 119, "errorDetailMessage": "Type is not found for URI configuration/entityTypes/HCP45 and tenant LocalTenantId" }, "successful": false } ] Note: Even if you are updating only one entity, this response works the same way. You can check the cause of the problem that applied POST API in a script.
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 created by the request: `index` (required): An index of an entity object in the JSON array of entities that was created. `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. The API generates some properties, such as the URI, when it creates the entity object. `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`: if object is created but there were some problems. `status`: result of operation; possible values are `OK` or `failed`.

Examples

Table 7. Request example
This request creates entities for Ivan and John based on the Individual entity type. `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": "John" }] } }, { "type": "configuration/entityTypes/Organization" } ]`

This request creates entities for Ivan and John based on the Individual entity type.

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": "John"
			}]
		}
	},
	{
		"type": "configuration/entityTypes/Organization"
	}
]

This example shows the response the API returns for the create 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"
}]

Accelerate the Value of Data

Create entities

Request

Response

Examples

Footer