Get Entity by Crosswalk

Learn how to retrieve a full or partial entity object using a crosswalk value and source type.

Problem

When fetching entities by crosswalk using the GET API, incorrect entities were returned. After this was fixed, getting entities by crosswalk returned only entities that had a Reltio crosswalk.

Solution

Now, if an entity does not have any default crosswalk (Reltio) and the searchable crosswalk does not belong to any other entity, then the entity is returned by ID.

This operation returns an entity object (full or partial) by crosswalk (crosswalkValue and sourceType) from a tenant.

Request

GET {TenantURL}/entities/_byCrosswalk/{crosswalkValue}?type={sourceType}

When the crosswalk value has special characters, use the POST method with the crosswalk value in the body, as shown in this example:

POST {TenantURL}/entities/_byCrosswalk?type=JDE

{ "crosswalkValue":"92101|C/O RANDOM HOUSE INC|CHASE MANHATTAN BANK|GPO BOX 5323|NEW YORK|NY|10087|US" }

Table 1. Parameters
Parameter		Required	Description
Headers	`Authorization`	Yes	Information about authentication access token in format Bearer `<accessToken>` (see details in Authentication API).
Query	`crosswalkValue`	Yes	ID of the object in the source system defined in the `sourceType` property. This property is required ONLY for entities. Example: an entity comes from Facebook source system and its identifier in Facebook is 'id3562'. For this entity, we will have a crosswalk with type 'configuration/sources/Facebook', value will be '`id3562`' and `url` 'https://www.facebook.com/id3562'
	`sourceType`	Yes	Source type of the crosswalk. This is a reference to the source configuration by its URI. A crosswalk can have just one source.
	`sourceTable`	No	`sourceTable` parameter of crosswalk.
	`options`	No	Comma-separated list of different options which affect the entity's JSON content in the response. Available options: `sendHidden`: disabled by default, entity's JSON will contain hidden attributes if this option is enabled. `ovOnly`: return only attribute values that have `ov=true` flag. `nonOvOnly`: return only attribute values that have `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 will not appear in the response. `showAppliedSurvivorshipRules` - Returns the survivorship determination logic used to determine the OV value of an attribute, down to the lowest level for each attribute and each value of an attribute. In the `appliedSurvivorshipRules` object, the key is the main survivorship strategy. If fallback rules are present, the value is either a string for a single fallback or an array for multiple fallbacks. This response does not include crosswalk details. A sample response is given below: `{ "ovDetails": { "appliedSurvivorshipRules": { "Frequency": "LUD" }, "appliedSurvivorshipGroup": "default", "participationStatus": "strategy" } }` Note: The `participationStatus` property indicates how an attribute value participates in OV calculation. This property supports the following enum values: `ignored`, `pinned`, `end-dated-crosswalk`, `not-participated`, and `strategy`. `explainOv`: Returns additional survivorship diagnostics in the `ovDetails` section of the response. The diagnostic fields are populated only when `explainOv` is provided. The response includes all fields returned by `showAppliedSurvivorshipRules`, and the following root-level and rule-level fields: `appliedSurvivorshipGroup`: Applied survivorship group for the attribute value. `participationStatus`: Indicates how the attribute value participates in OV calculation. `matchedFilters`: Filters from the business configuration that matched during survivorship evaluation. `unmatchedFilters`: Filters from the business configuration that did not match during survivorship evaluation. `winnerCrosswalks`: Final list of winner crosswalks for the OV value. `appliedSurvivorshipRule`: The survivorship rule applied at the current level. `winningSources`: Winner crosswalks from the rule applied at the current level. `sourcesForOv`: Reference to the `sourcesForOv` setting from the business configuration for the current rule. `fallbackCriteria`: Reference to the fallback criteria from the business configuration. Supported values are `ZERO`, `ZERO_OR_MORE_THAN_ONE`, and `MORE_THAN_ONE`. `fallbacks`: List of fallback rules. Each fallback contains the same fields as the parent rule: `appliedSurvivorshipRule`, `winningSources`, `sourcesForOv`, `fallbackCriteria`, and `fallbacks`. A sample response is given below: { "ovDetails": { "winnerCrosswalks": [ "configuration/sources/<sourceName>" ], "appliedSurvivorshipGroup": "default", "participationStatus": "strategy", "unmatchedFilters": [ { "and": [ { "uri": "configuration/entityTypes/HCO/attributes/MultipleFilters", "value": "matchedValue", "operator": "ne" } ] } ], "appliedSurvivorshipRules": { "appliedSurvivorshipRule": "Frequency", "fallbacks": [ { "appliedSurvivorshipRule": "LUD", "fallbacks": [], "fallbackCriteria": "MORE_THAN_ONE", "winningSources": [ "configuration/sources/<sourceName>" ], "sourcesForOv": [ "configuration/sources/<sourceName>" ] } ], "fallbackCriteria": "MORE_THAN_ONE", "winningSources": [ "configuration/sources/<sourceName>" ], "sourcesForOv": [ "configuration/sources/<sourceName>" ] }, "matchedFilters": [ { "and": [ { "uri": "configuration/entityTypes/HCO/attributes/MultipleFilters", "value": "unmatchedValue", "operator": "ne" } ] }, { "equals": [ { "uri": "configuration/entityTypes/HCO/attributes/MultipleFilters", "value": "matchedValue" } ] } ] } }

Response

JSON Array containing Object representing object with provided crosswalk.

Request

GET {TenantURL}/entities/_byCrosswalk/5NEzNON?type=Reltio
                Headers: Authorization: Bearer <accessToken>

Response

[
   {
      "index":0,
      "object":{
         "uri":"entities/5NEzNON",
         "type":"configuration/entityTypes/HCP",
         "createdBy":"alexey.matveev",
         "createdTime":1571297454707,
         "updatedBy":"alexey.matveev",
         "updatedTime":1571297454707,
         "attributes":{
            "FirstName":[
               {
                  "type":"configuration/entityTypes/HCP/attributes/FirstName",
                  "ov":true,
                  "value":"Matveev",
                  "uri":"entities/5NEzNON/attributes/FirstName/L5Htecg7"
               }
            ]
         },
         "isFavorite":false,
         "crosswalks":[
            {
               "uri":"entities/5NEzNON/crosswalks/L5HtegwN",
               "type":"configuration/sources/AMA",
               "value":"u0",
               "reltioLoadDate":"2019-10-17T07:30:54.707Z",
               "sourcePublishDate":"1970-01-01T00:00:00.000Z",
               "createDate":"2019-10-17T07:30:54.707Z",
               "updateDate":"2019-10-17T07:30:54.707Z",
               "attributes":[
                  "entities/5NEzNON/attributes/FirstName/L5Htecg7"
               ],
               "singleAttributeUpdateDates":{

               }
            }
         ],
         "analyticsAttributes":{

         },
         "label":"Matveev",
         "secondaryLabel":""
      },
      "successful":true
   }
]

Unify and manage your data

Get Entity by Crosswalk

Footer