Search before create
Learn how to search for existing entities before creating new entities or updating existing entity details.
The Search before create API operates in a similar way to the entities API, but it is used to check if the entity exists before creating it using the entities API. For example, a source system encounters what appears to be a new customer. With this API, you can propose to create the new profile in Reltio while at the same time checking whether a profile already exists in Reltio with a sufficiently similar combination of PII attributes.
Logic is as follows:
If the entity crosswalk included in the request body already exists in Reltio, the profile is updated.
If the response returns any existing profiles, the condition specified in the
applyIfNoMatchesquery is used.
Before you create or update entity details using the entities API, use this API to check if the attributes being updated are available in the entity or not. For example, you want to check if the entity has an existing phone number or email. When you send the request, the entity is updated with the phone number and email if the crosswalk included in the request body exists. If the request returns any existing profiles, the condition specified in the applyIfNoMatches query is used.
Request
POST /entities/_conditional| Parameter | Required | Description | |
|---|---|---|---|
| Headers | Authorization
| Yes | Information about authentication access token in the format "Bearer <accessToken>". For more information, see Authentication API. |
| Query | search request parameters | Parameters to search for an entity record. For more information, see topic Entity Search. | |
| create entities parameters | Parameters to create or update an entity. For more information, see topic Create entities. | ||
applyIfNoMatches
| Yes | The condition based on which the request body is applied. If this is set to true, then a new entity is created only if there are no entities matching the search criteria. If this is set to false, then it creates/updates entity details if and only if there is at least one entity in tenant matching the search criteria. | |
returnMatches
| Yes | Determines whether to return the search results in the response. | |
| Body | Yes | JSON Array with objects representing entity objects to be created. For more information, see topic Create entities. | |
Sample request
POST: {{tenantURL}}/entities/_conditional?filter=(equals(type,'configuration/entityTypes/Individual') and fuzzy(attributes.FirstName,'Henry') and fuzzy(attributes.LastName,'Lang') and fuzzy(attributes.Addresses.AddressLine1,'7708 Beech Tree Rd') and equals(attributes.Addresses.City,'Bethesda') and (equals(attributes.Phone.Number,'(202) 878-2310') or equals(attributes.Email.Email,'henry.lang@gmail.com')))&options=partialOverride&applyIfNoMatches=true&returnMatches=true[
{
"type": "configuration/entityTypes/Individual",
"attributes": {
"FirstName": [{"value": "Henry"}],
"LastName": [{"value": "Lang"}],
"Email": [
{"value": {
"Type": [{"value": "Home"}],
"Email": [{"value": "henry.lang@icloud.com"}]}
}
],
"Phone": [
{"value": {
"Type": [{"value": "Mobile"}],
"Number": [{"value": "(202) 878-2310"}],
"CountryCode": [{"value": "US"}]}
}
],
"Addresses": [
{"value": {
"AddressType": [{"value": "Home"}],
"AddressLine1": [{"value": "7708 Beech Tree Rd"}],
"City": [{"value": "Bethesda"}],
"StateProvince": [{"value": "Maryland"}],
"Country": [{"value": "US"}]}
}
]
},
"crosswalks": [{
"type": "configuration/sources/Web",
"value": "x55332b13f14g11118"}]
}
]Response
[
{
"type": "configuration/entityTypes/Individual",
"attributes": {
"FirstName": [{"value": "Henry"}],
"LastName": [{"value": "Lang"}],
"Email": [
{"value": {
"Type": [{"value": "Home"}],
"Email": [{"value": "henry.lang@icloud.com"}]}
}
],
"Phone": [
{"value": {
"Type": [{"value": "Mobile"}],
"Number": [{"value": "(202) 878-2310"}],
"CountryCode": [{"value": "US"}]}
}
],
"Addresses": [
{"value": {
"AddressType": [{"value": "Home"}],
"AddressLine1": [{"value": "7708 Beech Tree Rd"}],
"City": [{"value": "Bethesda"}],
"StateProvince": [{"value": "Maryland"}],
"Country": [{"value": "US"}]}
}
]
},
"crosswalks": [{
"type": "configuration/sources/Web",
"value": "x55332b13f14g11118"}]
}
]