Entity Search

This operation searches for individual or multiple entities by attribute values, tags, type, and roles.

Note:

You can search Entity Records up to a maximum number of 10,000 items. You may use Search Entities with Cursor API to avoid this limitation. Also, you may use Entities Export API for large amounts of data.

You can conduct searches using Winner URIs. Our entities include loser crosswalks, and sometimes they match loser URIs. This might make it seem like searching by loser URI is possible — it's NOT possible.

Request - You can use one of the following endpoints to search for entities:

GET {TenantURL}/entities
GET {TenantURL}/entities/_search
POST {TenantURL}/entities/_search

Note: Reltio recommends that you use the POST method and pass the parameters through the request body.

Table 1. Parameters
Parameter		Required	Description
Header	`Authorization`	Yes	Information about authentication access token in format "Bearer `<accessToken>`" (see details in Authentication API).
Query	`filter`	No	Enables entities filtering by a condition. Format for filter query parameter: `filter=({Condition Type}[AND/OR {Condition Type}]*)` For more information see Filtering Entities .
	`select`	No	Comma-separated list of properties from entity structure that should be returned in a response. Allows you to return partial entity object. List of entity object properties you can find here-Entities. Additional system properties are: `attributes._lookupCodes`: return codes for lookup attributes. `attributes._lookupValues`: return values for lookup attributes. Example: `select=URI,label,attributes._lookupCodes,attributes._lookupValues`
	`max`	No	Positive Integer value to identify maximum number of entities to return in a response. Can be used to organize pagination in combination with the `offset` parameter. Default value is `50`.
	`offset`	No	Positive Integer value to identify starting what element in a result set should be returned in a response. Can be used to organize pagination in combination with the `max` parameter. Default value is `0`. Note: The updated maximum value and offset parameters, when combined, must not exceed the value of 10,000. Some examples of valid combinations are: offset=9900 and max=100 offset=9800 and max=200
	`sort`	No	Sort parameter is used with `Order` parameter. Sort parameter points to the attribute or a list of attributes where ordering must be applied. If you order the result set as ascending or descending (reversed), you must use the Sort parameter to list the attributes that must be used for ordering. Example: `sort=attributes.FirstName` Important: The sorting will not be used if this parameter is not provided or the value is not recognized. Sorting is available on multiple parameters combining the parameters using & sign. The & symbol is encoded as %26 in the request. Sorting priority of the parameters depends upon the order you have added the parameters in the request while using multiple sorting. `sort=attributes.FirstName` `sort=attributes.FirstName&attributes.LastName` At first, the resultset is sorted alphabetically by the attributes FirstName. The sorted result set will be sorted again by sort=attributes.LastName.
	`order`	No	Order of sorting. Applicable only in combination with the `sort` parameter. Possible values: `asc`: results are shown in ascending order. `desc`: results are shown in descending order. Default sorting is `asc`. Example: `order=desc`
	`options`	No	Comma-separated list of different options. Available options: `sendHidden`: disabled by default; entity's JSON will contain hidden attributes if this option is enabled. `searchByOv`: disabled by default, to search by all attributes with Operational Value (OV) only. You can use the `searchByOv` and `sortByOv` options in case of STATIC index OV strategy. If you use `searchByOv` option, sorting by OV works automatically. In case of NONE strategy, the `sortByOv` option is ignored. If you want to sort by OV, you should switch `indexOvStrategy` to STATIC. `ovOnly`: return only attribute values that have the `ov=true` flag. `nonOvOnly`: return only attribute values that have the `ov=false` flag. If you have a nested or reference attribute value, where `ov=true`, but sub-attributes, where `ov=false`, then these sub-attributes do not appear in the response. Example: `options=searchByOv` `cleanEntity`- Set this option to `true` to get entities without certain properties. Here's what you get in the response: URI is null. Type of entity is available. createdBy, createdTime, updatedBy, and updatedTime are included. Simple and nested attributes are displayed without the uri, ov, type, and label parameters. For refEntity and refRelation, the `uri`, `type`, `createDate`,`updateDate`, `attributeURIs`, `startRefPinned`, `endRefPinned`, `startRefIgnored`, `endRefIgnored`, and `objectURI` are included. Field crosswalks type is updated with its `short name`, `reltioLoadDate`, `createDate`, and `updateDate`. Field attributes for crosswalk block contains only short URIs. singleAttributeUpdateDates field for crosswalk block is empty. `analyticsAttributes` is not included.
	`defaultMaxValues`	No	Specifies maximum number of values listed in attributes. This restriction is intended for UI convenience in the case of very long lists of values in some attributes. Example: `defaultMaxValues=10`
	`activeness`	No	Activeness is the indicator of an entity that is currently effective. The following options are available. These options are active, all, and not_active. active - This option allows you to search only active entities. This is the default option. all - This option allows you to search for active or expired entities. expired - This option allows you to search for only expired entities. Example: `activeness=all`
	`scoreEnabled`	No	When set to `true`, documents with search hits in labels get more search relevance score. The default value is `false`.
Body (Only for the `POST` method)		No	Indicates the JSON body that can have all the same fields as supported in the query parameters. Note: The query parameters have priority and override the body parameters. Example: `{ "filter": "(equals(type,'configuration/entityTypes/Organization'))", "select": "uri,label,attributes._lookupCodes,attributes._lookupValues", "max": 10, "offset": 120, "sort": "attributes.FirstName", "order": "desc", "options": "sortByOV,ovOnly", "defaultMaxValues": 10, "activeness": "active", "scoreEnabled": true }`

Response

JSON array of entity objects from the tenant (that match the filter request) in the format and order that is defined by the query parameters.

Request-Find Individual Entities

GET {TenantURL}/entities?filter=(equals(type,'configuration/entityTypes/Individual'))&max=2
Headers: Authorization: Bearer 204938ca-2cf7-44b0-b11a-1b4c59984512

Response

GET {TenantURL}/entities?filter=(equals(type,'configuration/entityTypes/Individual'))&max=2
Headers:
Authorization: Bearer 204938ca-2cf7-44b0-b11a-1b4c59984512,
[ { "URI": "entities/20",      ... },
{ "URI": "entities/142",        ... } ]

The following examples explain how to include activeness in your GET Entities API call. This query will return all HCP entities with LastName = Smith which are not active:

GET {{TenantURL}}/entities?activeness=not_active&filter=((equals(type,'configuration/entityTypes/HCP') 
and 
equals(attributes.LastName,'Smith')))

Similarly, the following query returns all HCP entities with LastName fuzzy matching Smit which are active.

GET {{TenantURL}}/entities?activeness=active&filter=((equals(type,'configuration/entityTypes/HCP') and fuzzy(attributes.LastName,'Smit')))

Accelerate the Value of Data

Entity Search

Request-Find Individual Entities

Footer