home

Developer resources

ReltioProductsDeveloper resourcesRolesApplicationsObjectives
ReltioProductsDeveloper resourcesRolesApplicationsObjectives

Unify and manage your data

Show Contents

thumbnailDeveloper resources

Entities API

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
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 booleanNoWhether the response contains created entities: true (default) or false.
optionsarray(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).

executeLCAbooleanNoWhether 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
ParameterTypeRequiredDescription
entities_to_createarrayYesOne 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 CodeMessageDescription
200Entities 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 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 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 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"
}]

Updated on December 9, 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

© 2024 The RELTIO® mark is a registered trademark of Reltio, Inc. in the United States and other countries; DataDriven and Reltio Data Cloud are trademarks of Reltio, Inc. Other names or marks are trademarks of their respective owners.

Terms, Privacy Policy, and