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 for each attribute and each value of an attribute. When you use showAppliedSurvivorshipRules, the ovDetails section has the following fields:
    • appliedSurvivorshipRules (legacy): Contains the applied survivorship strategy and fallback information. This legacy response format is retained for backward compatibility.

    • appliedSurvivorshipRuleTree (recommended): Provides a more detailed version of the applied survivorship strategy and fallback strategies, including source ordering information where applicable. The following response fields are supported:

      • appliedSurvivorshipRule: Name of the survivorship strategy applied at the current level.
      • sourcesUriOrder: Ordered list of source URIs for an SRC_SYS strategy. This field is omitted for other strategies and when sourcesUriOrderDerivedFrom is none.
      • sourcesUriOrderDerivedFrom: Indicates how sourcesUriOrder was derived for an SRC_SYS strategy. The following response fields are supported:
        • mapping: The source order is configured at the mapping level. The API returns the sourcesUriOrder value from the L3 mapping configuration.
        • group: The source order is configured at the group level. The API returns the sourcesUriOrder value from the L3 group configuration.
        • priority: The source order is derived from sources associated with the attribute that have an L3 priority. The API returns the sources in descending priority order.
        • none: No priority or source order is configured, or no applicable source order is found. The response omits sourcesUriOrder.
      • fallbacks: List of fallback strategies. Each fallback contains appliedSurvivorshipRule and fallbacks. An SRC_SYS fallback also includes sourcesUriOrderDerivedFrom and, where applicable, sourcesUriOrder.

    A sample response is given below:

    {
      "ovDetails": {
        "appliedSurvivorshipRules": {
          "SRC_SYS": [
            "MinValue"
          ]
        },
        "appliedSurvivorshipRuleTree": {
          "appliedSurvivorshipRule": "SRC_SYS",
          "sourcesUriOrder": [
            "configuration/sources/SRC1",
            "configuration/sources/SRC2"
          ],
          "sourcesUriOrderDerivedFrom": "mapping",
          "fallbacks": [
            {
              "appliedSurvivorshipRule": "MinValue",
              "fallbacks": []
            }
          ]
        },
        "appliedSurvivorshipGroup": "GroupA",
        "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 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. Each object contains type, which identifies the source type URI, and value, which identifies the crosswalk value.
    • appliedSurvivorshipRule: The survivorship rule applied at the current level.
    • sourcesUriOrder: Displays an ordered list of source URIs for a SRC_SYS strategy. This field is omitted for other strategies and when sourcesUriOrderDerivedFrom is none.

    • sourcesUriOrderDerivedFrom: Indicates how sourcesUriOrder was derived for an SRC_SYS strategy. The following values are supported:
      • mapping: The source order is configured at the mapping level. The API returns the sourcesUriOrder value from the L3 mapping configuration.
      • group: The source order is configured at the group level. The API returns the sourcesUriOrder value from the L3 group configuration.
      • priority: The source order is derived from sources associated with the attribute that have an L3 priority. The API returns the sources in descending priority order.
      • none: No priority or source order is configured, or no applicable source order is found. The response omits sourcesUriOrder.
    • winningCrosswalks: 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, winningCrosswalks, sourcesForOv, fallbackCriteria, and fallbacks. An SRC_SYS fallback also includes sourcesUriOrderDerivedFrom and, where applicable, sourcesUriOrder.
    A sample response is given below:
    {
      "ovDetails": {
        "winnerCrosswalks": [
          {
            "type": "configuration/sources/LNKD",
            "value": "LNKD_RANK"
          }
        ],
        "appliedSurvivorshipGroup": "default",
        "participationStatus": "strategy",
        "unmatchedFilters": [
          {
            "and": [
              {
                "uri": "configuration/entityTypes/HCO/attributes/MultipleFilters",
                "value": "matchedValue",
                "operator": "ne"
              }
            ]
          }
        ],
        "appliedSurvivorshipRules": {
          "appliedSurvivorshipRule": "SRC_SYS",
          "sourcesUriOrder": [
            "configuration/sources/LNKD",
            "configuration/sources/SRC2"
          ],
          "sourcesUriOrderDerivedFrom": "mapping",
          "fallbacks": [
            {
              "appliedSurvivorshipRule": "MinValue",
              "fallbacks": [],
              "fallbackCriteria": "MORE_THAN_ONE",
              "winningCrosswalks": [
                {
                  "type": "configuration/sources/LNKD",
                  "value": "LNKD_RANK"
                }
              ],
              "sourcesForOv": [
                "configuration/sources/LNKD"
              ]
            }
          ],
          "fallbackCriteria": "MORE_THAN_ONE",
          "winningCrosswalks": [
            {
              "type": "configuration/sources/LNKD",
              "value": "LNKD_RANK"
            }
          ],
          "sourcesForOv": [
            "configuration/sources/LNKD"
          ]
        },
        "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 {your-access-token}

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