Unify and manage your data

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 (the primary and fallback strategies in order they were applied) for each attribute and each value of an attribute. A sample response is given below:
    {
      "ovDetails": {
        "appliedSurvivorshipRules": {
          "Aggregation": [
            "Aggregation ",
            "LUD"
          ]
        },
        "appliedSurvivorshipGroup": "default",
        "participationStatus": "strategy",
        "matchedFilters": [
          {
            "and": [
              {
                "uri": "configuration/entityTypes/HCO/attributes/MultipleFilters",
                "value": "unmatchedValue",
                "operator": "ne"
              }
            ]
          }
        ],
        "unmatchedFilters": [
          {
            "uri": "configuration/entityTypes/HCO/attributes/MultipleFilters",
            "value": "matchedValue",
            "operator": "ne"
          }
        ]
      }
    }
    Note: The ovParticipationStatus property indicates how an attribute value participates in OV calculation. It explicitly represents values that are excluded or handled differently during OV processing. 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, including matched and unmatched filters as defined in the business configuration. It also includes all fields returned by showAppliedSurvivorshipRule. A sample response is given below:
{
  "ovDetails": {
    "appliedSurvivorshipRules": {
      "Aggregation": [
        "Aggregation ",
        "LUD"
      ]
    },
    "appliedSurvivorshipGroup": "default",
    "participationStatus": "strategy",
    "matchedFilters": [
      {
        "and": [
          {
            "uri": "configuration/entityTypes/HCO/attributes/MultipleFilters",
            "value": "unmatchedValue",
            "operator": "ne"
          }
        ]
      }
    ],
    "unmatchedFilters": [
      {
        "uri": "configuration/entityTypes/HCO/attributes/MultipleFilters",
        "value": "matchedValue",
        "operator": "ne"
      }
    ]
  }
}

Response

JSON Array containing Object representing object with provided crosswalk.

Request

GET {TenantURL}/entities/_byCrosswalk/5NEzNON?type=Reltio
                Headers: Authorization: Bearer 204938ca-2cf7-44b0-b11a-1b4c59984512

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
   }
]