Entity Search
This operation searches for individual or multiple entities by attribute values, tags, type, and roles.
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
POST
method and pass the parameters through the request body.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:
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:
| |
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: 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
| |
order | No | Order of sorting. Applicable only in combination with the sort parameter. Possible values:
asc .Example: | |
options | No | Comma-separated list of different options. Available options:
Example:
| |
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: | |
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.
Example: | |
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:
|
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')))
GET {{TenantURL}}/entities?activeness=active&filter=((equals(type,'configuration/entityTypes/HCP') and fuzzy(attributes.LastName,'Smit')))