Accelerate the Value of Data

Search Connections

Use this API to search and filter entities using attributes or crosswalk IDs.

Use the Search connections to search for entities using attributes or crosswalk IDs and retrieve these entities along with their relationships. You can also specify additional filtering on the attributes.

Let's use an example to understand the endpoint.

We have the following three entity types:

  • Person - James Young, Kira Lofton, James Smith

  • Agreement - Agreement1, Agreement2, Agreement3, Agreement4

  • Household - Household1, Household 2, Household3, Household4

We also have the following relations between these entity types:

  • Person to Agreement

  • Person to Household

PersonPerson to AgreementPerson to Household
James YoungAgreement 1, Agreement 2, Agreement 3Household1, Household2
Kira LoftonAgreement 3, Agreement 4Household3, Household4
James SmithAgreement 1, Agreement 4Household1
Using these examples, let us see how we can search for persons using attributes and crosswalk IDs and retrieve the corresponding agreement and household details for each person, all in a single API call.

Search entities by attributes

Searches for persons based on the attribute values, and returns the agreement and household details.
Request
POST /entities/_searchConnections?&max=25&returnFullRelations=false&returnAnalyticAttributes=false&returnReferenceAttributes=false&options=searchRelationsWithFilter

{
    "filter": "equals(type,'configuration/entityTypes/Person') and fuzzy(attributes.FirstName,'James')",
    "connections": [
        {
            "relationFilter": "equals(attributes.Status,'Active')",
            "outRelations": [
                {
                    "uri": "configuration/relationTypes/PersonToAgreement"
                }
            ]
        },
        {
            "outRelations": [
                {
                    "uri": "configuration/relationTypes/PersonToHousehold"
                }
            ]
        }
    ]
}
Query Parameters
  • max: The maximum number of entities to search for connections. The number of returned entities may exceed this max value as this parameter isn't applied to the search for connections, only to the initial entities search. Use connectedEntitiesMax to limit the connected entities returned.

  • options:

    • searchRelationsWithFilter: Searches relations using the Elastic Search (ES) service instead of the database. For additional options, see Get Entity.

  • returnAnalyticAttributes: Indicates whether analytical attributes must be returned for entities. If true, the latency of the API is higher, even if there are no analytical attributes for the returned entities.
  • returnFullRelations: If false, returns only the attributes and crosswalk details about the relation or connection details such as relationship type, start entity URI, and end entity URI. If true, returns all relations but the latency of the call is higher.

  • returnReferenceAttributes : Indicates whether reference attributes of the entity must be returned. If true, the latency of the API could be higher even if there are no reference attributes for returned entities. By default, this is set to false.

Body Parameters
  • connectedEntitiesMax: Limit the number of related entities returned for each main entity found. For example, if you configure connectedEntitiesMax to 20 and 10 entities are found in the entity search, then each of those 10 entities will have a maximum of 20 end objects.
  • connections:
    • inRelations: Specifies relation types where the entity is the end object.
    • outRelations: Specifies relation types where the entity is the start object.
    • relationFilter: Filters relations when query parameter options=searchRelationsWithFilter. The format is relationFilter=({Condition Type}[AND/OR {Condition Type}]*). For example, relationFilter=equals(attributes.AddressRank, '1'). For more information, see Elastic search based filtering.
  • filter: Defines conditions to match specific entities (e.g., type, name). The format is filter=({Condition Type}[AND/OR {Condition Type}]*). For more information see Filtering Entities.
Response
{
  "entities": [
    {
      "uri": "entities/01bpkU9",
      "type": "configuration/entityTypes/Agreement",
     "attributes": {
        "Type": [
          {
          	"value": "Copyright",
          }
        ],
        "Number": [
          {
             "value": "2",
          }
        ]
      },
      "isFavorite": false,
      "crosswalks": [
        {
           "type": "configuration/sources/HMS",
            "value": "Agreement2",
        }
      ],
      "analyticsAttributes": {},
      "label": "Copyright 2",
      "secondaryLabel": ""
    },
    {
      "uri": "entities/01bp87p",
      "type": "configuration/entityTypes/Household",
     "attributes": {
        "Caption": [
          {
            "value": "Household1",
          }
        ]
      },
      "isFavorite": false,
      "crosswalks": [
        {
          "value": "01bp87p",
        }
      ],
      "analyticsAttributes": {},
      "label": "Household1",
      "secondaryLabel": ""
    },
    {
      "uri": "entities/01bpokP",
      "type": "configuration/entityTypes/Agreement",
      "attributes": {
        "Type": [
          {
             "value": "Copyright",
          }
        ],
        "Number": [
          {
            "value": "3",
          }
        ]
      },
      "isFavorite": false,
      "crosswalks": [
        {
           "value": "Agreement3",
        }
      ],
      "analyticsAttributes": {},
      "label": "Copyright 3",
      "secondaryLabel": ""
    },
    {
      "uri": "entities/01bpt0f",
      "type": "configuration/entityTypes/Agreement",
      "attributes": {
        "Type": [
          {
             "value": "Copyright",
          }
        ],
        "Number": [
          {
             "value": "4",
           }
        ]
      },
      "isFavorite": false,
      "crosswalks": [
        {
          "value": "Agreement4",
        }
      ],
      "analyticsAttributes": {},
      "label": "Copyright 4",
      "secondaryLabel": ""
    },
    {
      "uri": "entities/01bpgDt",
      "type": "configuration/entityTypes/Agreement",
     "attributes": {
        "Type": [
          {
             "value": "Copyright",
	   }
        ],
        "Number": [
          {
            "value": "1",
          }
        ]
      },
      "isFavorite": false,
      "crosswalks": [
        {
          "value": "Agreement1",
        }
      ],
      "analyticsAttributes": {},
      "label": "Copyright 1",
      "secondaryLabel": ""
    },
    {
      "uri": "entities/01bpxGv",
      "type": "configuration/entityTypes/Person",
      "attributes": {
        "LastName": [
          {
             "value": "Smith",
          }
        ],
        "FirstName": [
          {
            "value": "James",
          }
        ]
      },
      "isFavorite": false,
      "crosswalks": [
        {
          "value": "01bpxGv",
        }
      ],
      "analyticsAttributes": {},
      "label": "James Smith,",
      "secondaryLabel": ""
    },
    {
      "uri": "entities/01bpCO5",
      "type": "configuration/entityTypes/Household",
      "attributes": {
        "Caption": [
          {
            "value": "Household2",
           }
        ]
      },
      "isFavorite": false,
      "crosswalks": [
        {
           "value": "01bpCO5",
        }
      ],
      "analyticsAttributes": {},
      "label": "Household2",
      "secondaryLabel": ""
    },
    {
      "uri": "entities/01boiYH",
      "type": "configuration/entityTypes/Person",
      "attributes": {
        "LastName": [
          {
            "value": "Young",
          }
        ],
        "FirstName": [
          {
            "value": "James",
          }
        ]
      },
      "isFavorite": false,
      "crosswalks": [
        {
          "value": "01boiYH",
        }
      ],
      "analyticsAttributes": {},
      "label": "James Young,",
      "secondaryLabel": ""
    }
  ],
  "relations": [
    {
      "uri": "relations/01bos8r",
      "type": "configuration/relationTypes/PersonToAgreement",
      "startObject": {
        "objectURI": "entities/01bpxGv"
      },
      "endObject": {
        "objectURI": "entities/01bpgDt"
      }
    },
    {
      "uri": "relations/01bob5p",
      "type": "configuration/relationTypes/PersonToHousehold",
      "startObject": {
        "objectURI": "entities/01boiYH"
      },
      "endObject": {
        "objectURI": "entities/01bp87p"
      }
    },
    {
      "uri": "relations/01boK2n",
      "type": "configuration/relationTypes/PersonToAgreement",
      "startObject": {
        "objectURI": "entities/01boiYH"
      },
      "endObject": {
        "objectURI": "entities/01bpkU9"
      }
    },
    {
      "uri": "relations/01bp0fN",
      "type": "configuration/relationTypes/PersonToHousehold",
      "startObject": {
        "objectURI": "entities/01bpxGv"
      },
      "endObject": {
        "objectURI": "entities/01bp87p"
      }
    },
    {
      "uri": "relations/01boOJ3",
      "type": "configuration/relationTypes/PersonToAgreement",
      "startObject": {
        "objectURI": "entities/01boiYH"
      },
      "endObject": {
        "objectURI": "entities/01bpokP"
      }
    },
    {
      "uri": "relations/01bowP7",
      "type": "configuration/relationTypes/PersonToAgreement",
      "startObject": {
        "objectURI": "entities/01bpxGv"
      },
      "endObject": {
        "objectURI": "entities/01bpt0f"
      }
    },
    {
      "uri": "relations/01boFmX",
      "type": "configuration/relationTypes/PersonToAgreement",
      "startObject": {
        "objectURI": "entities/01boiYH"
      },
      "endObject": {
        "objectURI": "entities/01bpgDt"
      }
    },
    {
      "uri": "relations/01bofM5",
      "type": "configuration/relationTypes/PersonToHousehold",
      "startObject": {
        "objectURI": "entities/01boiYH"
      },
      "endObject": {
        "objectURI": "entities/01bpCO5"
      }
    }
  ]
}

Search entities by URIs

Searches entities by URIs and returns their agreement and household details. In the URI parameter, specify a list of entity URIs, separated by a comma.
Request
POST /entities/_searchConnections?uris=entities/01bomoX
[
    {
        "outRelations": [
            {
                "uri": "configuration/relationTypes/PersonToAgreement"
            }
        ]
    },
    
        "outRelations": [
            {
                "uri": "configuration/relationTypes/PersonToHousehold"
            }
        ]
    }
]
Response
{
  "entities": [
    {
      "uri": "entities/01bpKub",
      "type": "configuration/entityTypes/Household",
      "createdBy": "sergey.zagorodin@reltio.com",
      "createdTime": 1644904339566,
      "updatedBy": "sergey.zagorodin@reltio.com",
      "updatedTime": 1644904339566,
      "attributes": {
        "Caption": [
          {
            "value": "Household4",
          }
        ]
      },
      "isFavorite": false,
      "crosswalks": [
        {
          "type": "configuration/sources/Reltio",
          "value": "01bpKub",
        }
      ],
      "analyticsAttributes": {},
      "label": "Household4",
      "secondaryLabel": ""
    },
    {
      "uri": "entities/01bomoX",
      "type": "configuration/entityTypes/Person",
      "attributes": {
        "LastName": [
          {
             "value": "Lofton",
          }
        ],
        "FirstName": [
          {
            "value": "Kira",
          }
        ]
      },
      "isFavorite": false,
      "crosswalks": [
        {
          "type": "configuration/sources/Reltio",
          "value": "01bomoX",
        }
      ],
      "analyticsAttributes": {},
      "label": "Kira Lofton,",
      "secondaryLabel": ""
    },
    {
      "uri": "entities/01bpt0f",
      "type": "configuration/entityTypes/Agreement",
      "attributes": {
        "Type": [
          {
             "value": "Copyright",
          }
        ],
        "Number": [
          {
             "value": "4",
          }
        ]
      },
      "isFavorite": false,
      "crosswalks": [
        {
           "type": "configuration/sources/HMS",
           "value": "Agreement4",
        }
      ],
      "analyticsAttributes": {},
      "label": "Copyright 4",
      "secondaryLabel": ""
    },
    {
      "uri": "entities/01bpGeL",
      "type": "configuration/entityTypes/Household",
      "attributes": {
        "Caption": [
          {
             "value": "Household3",
          }
        ]
      },
      "isFavorite": false,
      "crosswalks": [
        {
           "type": "configuration/sources/Reltio",
           "value": "01bpGeL",
        }
      ],
      "analyticsAttributes": {},
      "label": "Household3",
      "secondaryLabel": ""
    },
    {
      "uri": "entities/01bpokP",
      "type": "configuration/entityTypes/Agreement",
      "attributes": {
        "Type": [
          {
            "value": "Copyright",
          }
        ],
        "Number": [
          {
             "value": "3",
          }
        ]
      },
      "isFavorite": false,
      "crosswalks": [
        {
           "type": "configuration/sources/HMS",
           "value": "Agreement3",
        }
      ],
      "analyticsAttributes": {},
      "label": "Copyright 3",
      "secondaryLabel": ""
    }
  ],
  "relations": [
    {
      "uri": "relations/01bonsb",
      "type": "configuration/relationTypes/PersonToHousehold",
      "startRefPinned": false,
      "startRefIgnored": false,
      "endRefPinned": false,
      "endRefIgnored": false,
      "attributes": {},
      "crosswalks": [
        {
           "type": "configuration/sources/Reltio",
           "value": "01bonsb",
        }
      ],
      "startObject": {
        "objectURI": "entities/01bomoX",
        "crosswalks": []
      },
      "endObject": {
        "objectURI": "entities/01bpKub",
        "crosswalks": []
      }
    },
    {
      "uri": "relations/01boSZJ",
      "type": "configuration/relationTypes/PersonToAgreement",
      "startRefPinned": false,
      "startRefIgnored": false,
      "endRefPinned": false,
      "endRefIgnored": false,
      "attributes": {
        "Type": [
          {
            "value": "RN",
          }
        ],
        "Commenters": [
          {
             "value": "thermostat",
          }
        ]
      },
      "crosswalks": [
        {
          "value": "01boSZJ",
         }
        }
      ],
      "startObject": {
        "objectURI": "entities/01bomoX",
        "crosswalks": []
      },
      "endObject": {
        "objectURI": "entities/01bpokP",
        "crosswalks": [
          {
            "uri": "entities/01bpokP/crosswalks/D0Z6TrJ",
            "type": "configuration/sources/HMS",
            "value": "Agreement3"
          }
        ]
      }
    },
    {
      "uri": "relations/01bojcL",
      "type": "configuration/relationTypes/PersonToHousehold",
      "startRefPinned": false,
      "startRefIgnored": false,
      "endRefPinned": false,
      "endRefIgnored": false,
      "attributes": {},
      "crosswalks": [
        {
          "type": "configuration/sources/Reltio",
          "value": "01bojcL",
        }
      ],
      "startObject": {
        "objectURI": "entities/01bomoX",
        "crosswalks": []
      },
      "endObject": {
        "objectURI": "entities/01bpGeL",
        "crosswalks": []
      }
    },
    {
      "uri": "relations/01boWpZ",
      "type": "configuration/relationTypes/PersonToAgreement",
      "startRefPinned": false,
      "startRefIgnored": false,
      "endRefPinned": false,
      "endRefIgnored": false,
      "attributes": {
        "Type": [
          {
             "value": "Resident",
          }
        ],
        "Commenters": [
          {
             "value": "clock, watch",
          }
        ]
      },
      "crosswalks": [
        {
           "type": "configuration/sources/Reltio",
           "value": "01boWpZ",
         }
      ],
      "startObject": {
        "objectURI": "entities/01bomoX",
        "crosswalks": []
      },
      "endObject": {
        "objectURI": "entities/01bpt0f",
        "crosswalks": [
          {
            "uri": "entities/01bpt0f/crosswalks/D0Z6ge5",
            "type": "configuration/sources/HMS",
            "value": "Agreement4"
          }
        ]
      }
    }
  ]
}